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 d6a22e7b7e..0000000000 --- a/.github/ISSUE_TEMPLATE/new-c---2017-stl-library-documentation-topic-.md +++ /dev/null @@ -1,13 +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: '' ---- -{Use this template to request **new** documentation to cover a feature area in the ISO C++17 standard library. Replace this text in curly braces with a description of the feature area to cover. Include a link to the proposal paper that introduced the issue (for example, `[N4086 Removing Trigraphs??!](https://wg21.link/n4086)`), or cite the chapter and section number or \[short.name] in the C++ standard that describes the feature. Add the Visual Studio version that first implements this feature. If you don't know or don't have these values, then this issue template probably isn't the right one to use. - -If documentation already exists on docs.microsoft.com for this feature area, and you're requesting an update, bug fix, or clarification, don't use this template. Go to the article on docs.microsoft.com and use the **This page** button in the **Feedback** section at the bottom of the document to create a GitHub issue. Include a citation for the ISO standard feature area in your description.} - -ISO paper or location in the standard for this feature: {insert link or section here} -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 189349bd9a..0000000000 --- a/.github/ISSUE_TEMPLATE/new-c---2020-stl-library-documentation-topic-.md +++ /dev/null @@ -1,13 +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: '' ---- -{Use this template to request **new** documentation to cover a feature area in the ISO C++20 standard library. Replace this text in curly braces with a description of the feature area to cover. Include a link to the proposal paper that introduced the issue (for example, `[N4086 Removing Trigraphs??!](https://wg21.link/n4086)`), or cite the chapter and section number or \[short.name] in the C++ standard that describes the feature. Add the Visual Studio version that first implements this feature. If you don't know or don't have these values, then this issue template probably isn't the right one to use. - -If documentation already exists on docs.microsoft.com for this feature area, and you're requesting an update, bug fix, or clarification, don't use this template. Go to the article on docs.microsoft.com and use the **This page** button in the **Feedback** section at the bottom of the document to create a GitHub issue. Include a citation for the ISO standard feature area in your description.} - -ISO paper or location in the standard for this feature: {insert link or section here} -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 7231cf6266..0000000000 --- a/.github/ISSUE_TEMPLATE/new-c---2023-stl-library-documentation-topic.md +++ /dev/null @@ -1,13 +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, STL doc work -assignees: '' ---- -{Use this template to request **new** documentation to cover a feature area proposed for the ISO C++23 standard library. Replace this text in curly braces with a description of the feature area to cover. Include a link to the proposal paper that introduced the issue (for example, `[N4086 Removing Trigraphs??!](https://wg21.link/n4086)`), or cite the chapter and section number or \[short.name] in the C++ standard that describes the feature. Add the Visual Studio version that first implements this feature. If you don't know or don't have these values, then this issue template probably isn't the right one to use. - -If documentation already exists on docs.microsoft.com for this feature area, and you're requesting an update, bug fix, or clarification, don't use this template. Go to the article on docs.microsoft.com and use the **This page** button in the **Feedback** section at the bottom of the document to create a GitHub issue. Include a citation for the ISO standard feature area in your description.} - -ISO paper or location in the standard for this feature: {insert link or section here} -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 35de11091d..0000000000 --- a/.github/ISSUE_TEMPLATE/new-c---stl-library-doc-topic-.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -name: 'New C++ STL library documentation topic' -about: Create a C++ doc tracking work item -title: '' -labels: STL doc work -assignees: '' ---- -{Use this template to request **new** documentation to cover a feature area in the ISO C++ standard library. Replace this text in curly braces with a description of the feature area to cover. Include a link to the tracking issue or PR in the [Microsoft/STL](https://github.com/microsoft/STL/pulls) repo that implements the feature area. If relevant, include a link to the proposal paper that introduced the issue (for example, `[N4086 Removing Trigraphs??!](https://wg21.link/n4086)`), or cite the chapter and section number or \[short.name] in the C++ standard that describes the feature. Add the Visual Studio version that first implements this feature. If you don't know or don't have these values, then this issue template probably isn't the right one to use. - -If documentation already exists on docs.microsoft.com for this feature area, and you're requesting an update, bug fix, or clarification, don't use this template. Go to the article on docs.microsoft.com and use the **This page** button in the **Feedback** section at the bottom of the document to create a GitHub issue. If possible, include a citation for the ISO standard feature area in your description.} - -[Microsoft/STL](https://github.com/microsoft/STL/pulls) PR, ISO paper or location in the standard for this feature: {insert link or section here} -First implemented in: {VS 20YY major.minor} diff --git a/.github/ISSUE_TEMPLATE/new-c--20-compiler-doc-topic.md b/.github/ISSUE_TEMPLATE/new-c--20-compiler-doc-topic.md deleted file mode 100644 index b27ff51d56..0000000000 --- a/.github/ISSUE_TEMPLATE/new-c--20-compiler-doc-topic.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -name: 'New C++20 compiler documentation topic' -about: Create a C++ doc tracking work item -title: '' -labels: C++20, Standard doc work -assignees: '' ---- -{Use this template to request **new** documentation to cover a compiler feature area in the ISO C++20 standard. Replace this text in curly braces with a description of the feature area to cover. Include a link to the proposal paper that introduced the issue (for example, `[N4086 Removing Trigraphs??!](https://wg21.link/n4086)`), or cite the chapter and section number or \[short.name] in the C++ standard that describes the feature. Add the Visual Studio version that first implements this feature. If you don't know or don't have these values, then this issue template probably isn't the right one to use. - -If documentation already exists on docs.microsoft.com for this feature area, and you're requesting an update, bug fix, or clarification, don't use this template. Go to the article on docs.microsoft.com and use the **This page** button in the **Feedback** section at the bottom of the document to create a GitHub issue. If possible, include a citation for the ISO standard feature area in your description.} - -ISO paper or location in the standard for this feature: {insert link or section here} - -First implemented in: {VS 20YY major.minor} diff --git a/.github/ISSUE_TEMPLATE/new-c--23-compiler-doc-topic.md b/.github/ISSUE_TEMPLATE/new-c--23-compiler-doc-topic.md deleted file mode 100644 index 7f86f82da5..0000000000 --- a/.github/ISSUE_TEMPLATE/new-c--23-compiler-doc-topic.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -name: 'New C++23 compiler documentation topic' -about: Create a C++ doc tracking work item -title: '' -labels: C++23, Standard doc work -assignees: '' ---- -{Use this template to request **new** documentation to cover a compiler feature area in the ISO C++23 standard. Replace this text in curly braces with a description of the feature area to cover. Include a link to the proposal paper that introduced the issue (for example, `[N4086 Removing Trigraphs??!](https://wg21.link/n4086)`), or cite the chapter and section number or \[short.name] in the C++ standard that describes the feature. Add the Visual Studio version that first implements this feature. If you don't know or don't have these values, then this issue template probably isn't the right one to use. - -If documentation already exists on docs.microsoft.com for this feature area, and you're requesting an update, bug fix, or clarification, don't use this template. Go to the article on docs.microsoft.com and use the **This page** button in the **Feedback** section at the bottom of the document to create a GitHub issue. If possible, include a citation for the ISO standard feature area in your description.} - -ISO paper or location in the standard for this feature: {insert link or section here} - -First implemented in: {VS 20YY 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 5d83ccf79d..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/MicrosoftDocs/cpp-docs", "git_repository_branch_open_to_public_contributors": "main", - "skip_source_output_uploading": false, "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 2491e65649..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", @@ -7745,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", @@ -13739,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/README.md b/README.md index e2a4e7c444..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://learn.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, 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 index e138ec5d6a..675ad2a215 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,7 +2,7 @@ ## Security -Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). +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. 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 daed637d1e..6c79ceaf15 100644 --- a/docs/assembler/arm/arm-assembler-command-line-reference.md +++ b/docs/assembler/arm/arm-assembler-command-line-reference.md @@ -2,7 +2,6 @@ title: "ARM Assembler command-line reference" description: "Reference guide to the Microsoft ARM assembler command-line options." ms.date: 05/09/2022 -ms.assetid: f7b89478-1ab5-4995-8cde-a805f0462c45 --- # ARM Assembler command-line reference @@ -98,7 +97,7 @@ A combination of zero or more of the following options: 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/master/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/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). + *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*. 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/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/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/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 1f62e48b55..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/01/2022 +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 @@ -45,12 +44,13 @@ The options listed in the following table: | **`/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. | +| **`/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. | @@ -71,7 +71,7 @@ The options listed in the following table: | **`/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, or 4. | +| **`/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. | 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 81f89fb5e8..0037f31377 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2010.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2010.md @@ -2,7 +2,7 @@ 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 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 2fd878773b..3f39de593f 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2034.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2034.md @@ -2,7 +2,7 @@ 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 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/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/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_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 9b16301649..68ff5addc6 100644 --- a/docs/atl-mfc-shared/cstring-argument-passing.md +++ b/docs/atl-mfc-shared/cstring-argument-passing.md @@ -14,7 +14,7 @@ When you define a class interface, you must determine the argument-passing conve ## 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 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 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 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. 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/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 b92a1c4353..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 @@ -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. @@ -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 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 c6fc7033fd..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 @@ -101,7 +100,7 @@ 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 diff --git a/docs/atl-mfc-shared/reference/cstringt-class.md b/docs/atl-mfc-shared/reference/cstringt-class.md index ffff1211a4..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. @@ -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/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/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/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/reference/atl-classes.md b/docs/atl/reference/atl-classes.md index e7c285dc49..36a3ed3f0d 100644 --- a/docs/atl/reference/atl-classes.md +++ b/docs/atl/reference/atl-classes.md @@ -1,6 +1,6 @@ --- 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"] --- 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/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/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/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/ccomsafearray-class.md b/docs/atl/reference/ccomsafearray-class.md index a1f79d65d6..d9c6729e91 100644 --- a/docs/atl/reference/ccomsafearray-class.md +++ b/docs/atl/reference/ccomsafearray-class.md @@ -526,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/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/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/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/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/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/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/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/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/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/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 ca9bea6c23..9e52425ed8 100644 --- a/docs/build-insights/reference/sdk/functions/stop-tracing-session.md +++ b/docs/build-insights/reference/sdk/functions/stop-tracing-session.md @@ -15,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 `StopTracingSession` function stops an ongoing tracing session and produces a raw trace file. You can pass raw trace files to the [Analyze](analyze.md), [AnalzeA](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 `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`. @@ -28,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); ``` 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 52d5de1c21..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. For more information, see [vcpkg.io](https://vcpkg.io/). +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 @@ -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/arm64-exception-handling.md b/docs/build/arm64-exception-handling.md index 610bfab46b..9bad5d2883 100644 --- a/docs/build/arm64-exception-handling.md +++ b/docs/build/arm64-exception-handling.md @@ -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. @@ -299,14 +299,20 @@ The unwind codes are encoded according to the table below. All unwind codes are | `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 non-volatile Int or FP register pair. | -| | 11100111: reserved | +| `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` | @@ -330,7 +336,7 @@ In instructions with large values covering multiple bytes, the most significant 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. +`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. @@ -357,7 +363,7 @@ The fields are as follows: - **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 isn't saved in stack - 01 = unchained function, `` is saved in stack - - 10 = chained function with signed return address + - 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. @@ -382,7 +388,7 @@ Step 6: Allocate remaining stack, including local area, `` pair, and out | 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** == 11 | 1 | `pacibsp` | `pac_sign_lr` | +| 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` | @@ -393,7 +399,7 @@ Step 6: Allocate remaining stack, including local area, `` pair, and out | 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 **CR** == 01 and **RegI** is an odd number, Step 2 and the last `save_rep` in step 1 are merged into one `save_regp`. +\* 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`. \*\* If **RegI** == **CR** == 0, and **RegF** != 0, the first `stp` for the floating-point does the predecrement. 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 index b327417270..9c78bc39f5 100644 --- a/docs/build/arm64ec-windows-abi-conventions.md +++ b/docs/build/arm64ec-windows-abi-conventions.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Overview of ARM64EC ABI conventions" 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 @@ -50,7 +50,7 @@ Special helper routines like `__chkstk_arm64ec` use custom calling conventions 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` | N/A | fixed(TEB) | fixed(TEB) | 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 | @@ -62,7 +62,7 @@ Special helper routines like `__chkstk_arm64ec` use custom calling conventions a | `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) | volatile | volatile | N/A | +| `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 | @@ -73,7 +73,7 @@ Special helper routines like `__chkstk_arm64ec` use custom calling conventions a 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 +## Register mapping for vector registers | ARM64EC register | x64 register | ARM64EC calling convention | ARM64 calling convention | x64 calling convention | |--|--|--|--|--| @@ -92,6 +92,12 @@ Special helper routines like `__chkstk_arm64ec` use custom calling conventions a 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. diff --git a/docs/build/building-on-the-command-line.md b/docs/build/building-on-the-command-line.md index 7d63f0944e..06332dd523 100644 --- a/docs/build/building-on-the-command-line.md +++ b/docs/build/building-on-the-command-line.md @@ -79,6 +79,9 @@ The Start menu folder and shortcut names vary depending on the installed version 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. @@ -144,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: diff --git a/docs/build/clang-support-msbuild.md b/docs/build/clang-support-msbuild.md index 5c13bc7ace..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: 09/20/2022 +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"] --- @@ -34,10 +34,16 @@ The Microsoft C++ Standard Library requires at least Clang 8.0.0. ::: moniker-end ::: moniker range="=msvc-160" -![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) +:::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" -![Screenshot of the Visual Studio installer with the Individual components tab selected and the C plus plus Clang components visible.](media/clang-install-vs2022.png) +:::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 ::: + ::: moniker-end ::: moniker range=">=msvc-160" @@ -47,9 +53,11 @@ Later versions of Visual Studio provide newer versions of the Clang toolset. The 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 change the value of the `LLVMInstallDir` property. For more information, see [Set a custom LLVM location](#custom_llvm_location). @@ -64,7 +72,9 @@ 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). @@ -97,7 +107,7 @@ 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. -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. +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 properties, edit, build, and debug @@ -105,6 +115,8 @@ After you have set up a Clang configuration, right-click again on the project no 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-vs.md b/docs/build/cmake-presets-vs.md index f14c59a8c6..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: 09/13/2022 +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 -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 2 adds support for schema versions 4 and 5. 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). +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`* 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. +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). + +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] > Close and reopen the folder in Visual Studio to activate the 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). @@ -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/buildsystems/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`* @@ -474,8 +485,8 @@ The *`CMakePresets.json`* file in [box2d-lite](https://github.com/esweet431/box2 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 5caf892144..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: 02/14/2022 -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 top-level `CMakeLists.txt` exists in a subfolder and not at the root of the workspace, 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 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: -:::image type="content" source="media/cmake-targets-view2.png" alt-text="Screenshot of the Solution Explorer Views window with the C Make Targets View highlighted."::: +:::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,6 +89,12 @@ 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: @@ -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 -In Visual Studio 2022 version 17.1 and later, 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. It supports 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/). +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 da1c2c7774..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 @@ -115,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 93805a8ab7..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 (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, 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. +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/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 4379cb9a7a..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,6 +26,12 @@ 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. diff --git a/docs/build/creating-and-managing-visual-cpp-projects.md b/docs/build/creating-and-managing-visual-cpp-projects.md index d8014dfeff..2441a8b327 100644 --- a/docs/build/creating-and-managing-visual-cpp-projects.md +++ b/docs/build/creating-and-managing-visual-cpp-projects.md @@ -1,29 +1,30 @@ --- -description: "Learn more about: creating and configuring Visual Studio C++ projects" -title: "Visual Studio Projects - C++" -ms.date: 04/20/2022 +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 collection of code files and assets such as icons, images, and so on, that are built together using 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. +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. +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 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) in Visual Studio 2017 and later. - +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" 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. The Console App project template is selected.](../build/media/vs2019-choose-console-app.png) + :::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 @@ -31,21 +32,22 @@ For cross-platform projects, or projects that use open-source libraries, we reco ::: moniker range="msvc-150" 1. Create a C++ project by choosing **File** > **New** > **Project**. + 1. Choose **Visual C++** in the left pane. In the center pane, a list of project templates appears: - ![Screenshot of the New Project dialog, showing available project templates for C++ such as Windows Console Application.](../overview/media/vs2017-new-project.png "Visual Studio 2017 New Project Dialog") + :::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."::: ::: moniker-end 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). -You can create your own project templates. For more information, see [How to: Create project templates](/visualstudio/ide/how-to-create-project-templates). +You can create your own project templates. For more information, see [Create project templates](/visualstudio/ide/how-to-create-project-templates). After you create a project, it appears in the [Solution Explorer](/visualstudio/ide/solutions-and-projects-in-visual-studio) window: - ![Screenshot of the Solution Explorer window, showing source files, header files, and resource files.](media/mathlibrary-solution-explorer-153.png) +:::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."::: -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**. +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**. The solution file coordinates build dependencies when you have multiple related projects. Compiler options are set at the project level. @@ -53,36 +55,38 @@ The solution file coordinates build dependencies when you have multiple related 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**. - ## Add third-party libraries to a project -Over 900 C++ open source libraries are available via 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. +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. +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) There are also commercial third-party libraries that you can install. Follow their installation instructions. ## Set compiler options and build properties -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). +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). ## Compile and run 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). - - -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 doesn't. All errors and warnings appear both in the Output Window and in the Error List when you build the 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). +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. - ![Screenshot of the Output window and Error list.](../overview/media/vs2017-output-error-list.png) +:::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."::: In the **Error List**, you can press **F1** on the highlighted error to go to its documentation topic. -## See also +## Related content -[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) +- [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 266c69b7d6..2b0f1f5ebe 100644 --- a/docs/build/creating-precompiled-header-files.md +++ b/docs/build/creating-precompiled-header-files.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Precompiled header files" title: "Precompiled Header Files" +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"] --- @@ -140,7 +140,7 @@ This table lists compiler options that might trigger an inconsistency warning wh | 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. | +| **`/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. | @@ -161,8 +161,11 @@ The code base of a software project is often contained in multiple C or C++ sour 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: + +:::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 @@ -255,7 +258,7 @@ Source file `ANOTHER.H`: // #ifndef __ANOTHER_H #define __ANOTHER_H -#include +#include void savemoretime( void ); #endif // __ANOTHER_H ``` @@ -269,7 +272,7 @@ Source file `STABLE.H`: // #ifndef __STABLE_H #define __STABLE_H -#include +#include void savetime( void ); #endif // __STABLE_H ``` @@ -285,7 +288,7 @@ Source file `UNSTABLE.H`: // #ifndef __UNSTABLE_H #define __UNSTABLE_H -#include +#include void notstable( void ); #endif // __UNSTABLE_H ``` @@ -297,9 +300,9 @@ Source file `APPLIB.CPP`: // 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 @@ -327,9 +330,9 @@ Source file `MYAPP.CPP`: // 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(); @@ -342,7 +345,7 @@ int main( void ) [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) +[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)\ 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/get-started-linux-cmake.md b/docs/build/get-started-linux-cmake.md index 693ada2f60..1ffb0fb6d2 100644 --- a/docs/build/get-started-linux-cmake.md +++ b/docs/build/get-started-linux-cmake.md @@ -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 @@ -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-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-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 ca7dcc9b70..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. | @@ -55,7 +55,7 @@ To create the file, right-click on an executable file in **Solution Explorer** a | `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/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/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-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/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 5d20f89c60..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 { 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 8ac6bdc9b4..f119173610 100644 --- a/docs/build/reference/advanced-property-page.md +++ b/docs/build/reference/advanced-property-page.md @@ -4,6 +4,7 @@ title: "Advanced Property Page (Project)" 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" @@ -96,6 +97,10 @@ Specifies the full version of the MSVC toolset that's used to build the project. Specifies the full version of the LLVM toolset that's used to build the project. This property is available when **LLVM (clang-cl)** is selected as the platform toolset, starting in Visual Studio 2019 version 16.9. For more information, see [Set a custom LLVM toolset version](..\clang-support-msbuild.md#custom_llvm_toolset). +### Enable MSVC Structured Output + +Specifies whether to enable [structured SARIF output](sarif-output.md), which enables the [**Problem Details** window](/visualstudio/ide/reference/problem-details-window) and hierarchical output in the [**Output** window](/visualstudio/ide/reference/output-window) in Visual Studio. + ## C++/CLI Properties ### Common Language Runtime support @@ -106,7 +111,13 @@ To programmatically access this property, see **`/arch:`**\[**`armv8.0`**-**`armv8.8`**] +>**`/arch:`**[[+feature]](feature-arm64.md)\ +>**`/arch:`**[[+feature]](feature-arm64.md) ## Arguments -**`/arch:armv8.0`** through **`/arch:armv8.8`**\ -Optional. Specifies minimum CPU extension requirements for ARMv8.x-A. The default is **`/arch:armv8.0`**. +**`/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 may specify a CPU extension requirement from Armv8.0-A through Armv8.8-A. However, 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 that was introduced with the ARMv8.1 extension, FEAT_LSE, but compiler support requires Visual Studio 2022 version 17.2 or later. +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). -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. +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 @@ -30,14 +45,19 @@ When you use [`/clr`](clr-common-language-runtime-compilation.md) to compile, ** 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. In the **Additional options** box, add *`/arch:armv8.0`* or higher. Choose **OK** to save your changes. +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-x64.md b/docs/build/reference/arch-x64.md index 6c944400a6..0bcf4ff202 100644 --- a/docs/build/reference/arch-x64.md +++ b/docs/build/reference/arch-x64.md @@ -2,30 +2,40 @@ description: "Learn more about: /arch (x64)" title: "/arch (x64)" ms.date: 06/30/2022 -ms.assetid: ecda22bf-5bed-43f4-99fb-88aedd83d9d8 +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) -Specifies the architecture for code generation on x64. 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). +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:SSE2`**\ +Enables Intel Streaming SIMD Extensions 2. The default instruction set is SSE2 if no **`/arch`** option is specified. + +**`/arch:SSE4.2`**\ +Enables Intel Streaming SIMD Extensions 4.2. + **`/arch:AVX`**\ -Enables the use of Intel Advanced Vector Extensions instructions. +Enables Intel Advanced Vector Extensions. **`/arch:AVX2`**\ -Enables the use of Intel Advanced Vector Extensions 2 instructions. +Enables Intel Advanced Vector Extensions 2. **`/arch:AVX512`**\ -Enables the use of Intel Advanced Vector Extensions 512 instructions. +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 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. +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. @@ -33,23 +43,33 @@ 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. +- **`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. - **`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, plus certain other optional features. Instructions for other operations were also added. +- **`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. + +- **`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. -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 diff --git a/docs/build/reference/arch-x86.md b/docs/build/reference/arch-x86.md index 1c5ae3c178..cb71ce0716 100644 --- a/docs/build/reference/arch-x86.md +++ b/docs/build/reference/arch-x86.md @@ -2,14 +2,16 @@ description: "Learn more about: /arch (x86)" title: "/arch (x86)" 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) -Specifies the architecture for code generation on x86. 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). +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 @@ -17,23 +19,26 @@ Specifies the architecture for code generation on x86. For more information on * Specifies no enhanced instructions and also specifies x87 for floating-point calculations. **`/arch:SSE`**\ -Enables the use of SSE instructions. +Enables Intel Streaming SIMD Extensions. **`/arch:SSE2`**\ -Enables the use of SSE2 instructions. This option is the default instruction set on x86 platforms if no **`/arch`** option is specified. +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. +Enables Intel Advanced Vector Extensions. **`/arch:AVX2`**\ -Enables the use of Intel Advanced Vector Extensions 2 instructions. +Enables Intel Advanced Vector Extensions 2. **`/arch:AVX512`**\ -Enables the use of Intel Advanced Vector Extensions 512 instructions. +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 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. +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. @@ -49,9 +54,11 @@ The **`/arch`** options refer to instruction set extensions with the following c - **`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, plus certain other optional features. Instructions for other operations were also added. +- **`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. + +- **`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. @@ -69,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) can't 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 the option changes the behavior of all floating-point to integer conversions, **`/QIfist`** 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) { @@ -81,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). 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/base-base-address.md b/docs/build/reference/base-base-address.md index a78fb4117b..1728032bac 100644 --- a/docs/build/reference/base-base-address.md +++ b/docs/build/reference/base-base-address.md @@ -1,10 +1,9 @@ --- description: "Learn more about: /BASE (Base address)" title: "/BASE (Base address)" -ms.date: 05/11/2022 +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) @@ -23,7 +22,7 @@ The **`/BASE`** linker option sets a base address for the program. It overrides 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 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. 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`* @@ -35,7 +34,7 @@ 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 @@ -46,9 +45,7 @@ Another way to set the base address is by using the *`BASE`* argument in a [`NAM ### 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 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 cc65f5e9a5..4f92e38d17 100644 --- a/docs/build/reference/c-cpp-prop-page.md +++ b/docs/build/reference/c-cpp-prop-page.md @@ -1,10 +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: 11/17/2022 +ms.date: 6/9/2023 ms.topic: "article" f1_keywords: ["VC.Project.VCCLCompilerTool.AdditionalModuleDirectories", "VC.Project.VCCLCompilerTool.ScanSourceForModuleDependencies"] -ms.assetid: 16375038-4917-4bd0-9a2a-26343c1708b7 --- # C/C++ Property Pages @@ -51,7 +50,7 @@ Specifies the type of debugging information generated by the compiler. This pro - **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 @@ -142,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 @@ -243,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 @@ -253,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 @@ -288,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), [`/arch (ARM64)`](arch-arm64.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 @@ -332,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. @@ -360,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 @@ -372,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 diff --git a/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md b/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md index 489f4c8f18..ffc60a41e9 100644 --- a/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md +++ b/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md @@ -6,8 +6,8 @@ ms.topic: "reference" 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) 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 17c26d9a7e..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,9 +1,8 @@ --- description: "Learn more about: Common macros for MSBuild commands and properties" title: "Common macros for MSBuild commands and properties" -ms.date: 03/15/2022 +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 @@ -11,9 +10,19 @@ Depending on your installation options, Visual Studio can make hundreds of macro ## 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. Select **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 @@ -22,29 +31,29 @@ This table describes a commonly used subset of the available macros; there are m | 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 '\\'. | +| **`$(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. | +| **`$(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 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. | +| **`$(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 '\\'. | +| **`$(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. | +| **`$(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. | +| **`$(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 '\\'. | +| **`$(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. | @@ -56,11 +65,11 @@ This table describes a commonly used subset of the available macros; there are m ## Obsolete macros -The build system for C++ was changed significantly 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) (**`%(item-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)`**. | +| **`$(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)`**. | @@ -68,7 +77,7 @@ The build system for C++ was changed significantly between Visual Studio 2008 an | **`$(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 in which the project wizards will 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. | +| **`$(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 diff --git a/docs/build/reference/compiler-command-line-syntax.md b/docs/build/reference/compiler-command-line-syntax.md index 6936391ed2..0f56baaed5 100644 --- a/docs/build/reference/compiler-command-line-syntax.md +++ b/docs/build/reference/compiler-command-line-syntax.md @@ -17,7 +17,7 @@ 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. For more information, see [Order of CL Options](order-of-cl-options.md).| +|*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. For more information, see [CL Command Files](cl-command-files.md).| diff --git a/docs/build/reference/compiler-options-listed-alphabetically.md b/docs/build/reference/compiler-options-listed-alphabetically.md index 595439b8a7..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: 11/07/2022 +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) | @@ -115,8 +120,9 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/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. | @@ -174,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++. | @@ -185,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. | @@ -192,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. | @@ -238,9 +246,9 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/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 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[-]`](zc-zerosizearraynew.md) | 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. | @@ -253,6 +261,9 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/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 7001df2cf0..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: 11/07/2022 +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. | @@ -165,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. | @@ -200,12 +205,12 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/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 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[-]`](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. | @@ -238,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. | @@ -247,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. | @@ -260,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. | @@ -299,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 @@ -323,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/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 2d60b22066..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. 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 index 36948fc6b1..85a515deba 100644 --- a/docs/build/reference/debug-generate-debug-info.md +++ b/docs/build/reference/debug-generate-debug-info.md @@ -1,7 +1,7 @@ --- description: "Learn more about: /DEBUG (Generate debug info)" title: "/DEBUG (Generate Debug Info)" -ms.date: 12/05/2022 +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 @@ -20,7 +20,7 @@ The **`/DEBUG`** option puts the debugging information from linked object and li 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. -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. In Visual Studio 2017, this option can sometimes greatly improve link times compared with **`/DEBUG:FULL`**. In Visual Studio 2019 and later, **`/DEBUG:FULL`** is faster than in earlier versions. Now, **`/DEBUG:FASTLINK`** isn't always faster than **`/DEBUG:FULL`**, and it's rarely more than twice as fast. +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. 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. @@ -28,7 +28,7 @@ The **`/DEBUG:FULL`** option moves all private symbol information from individua The **`/DEBUG:NONE`** option doesn't generate a PDB. -In Visual Studio 2015 and earlier versions, when you specify **`/DEBUG`** with no extra arguments, 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. 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 [`/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. diff --git a/docs/build/reference/def-specify-module-definition-file.md b/docs/build/reference/def-specify-module-definition-file.md index 5d6c186f61..42e938c3ff 100644 --- a/docs/build/reference/def-specify-module-definition-file.md +++ b/docs/build/reference/def-specify-module-definition-file.md @@ -1,10 +1,9 @@ --- description: "Learn more about: /DEF (Specify module-definition file)" title: "/DEF (Specify module-definition file)" -ms.date: 09/09/2022 +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) @@ -17,7 +16,7 @@ Specifies a module-definition file to the linker. ## Arguments *`filename`*\ -The name of a module-definition file (*`.def`*) to be passed to the linker. +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). ## Remarks @@ -28,9 +27,7 @@ To specify a *`.def`* file from within the development environment, add it to th ### To set this linker option in the Visual Studio development environment 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 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/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/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/execution-charset-set-execution-character-set.md b/docs/build/reference/execution-charset-set-execution-character-set.md index 1bfa82a706..2d67217025 100644 --- a/docs/build/reference/execution-charset-set-execution-character-set.md +++ b/docs/build/reference/execution-charset-set-execution-character-set.md @@ -28,7 +28,7 @@ You can use the **`/execution-charset`** option to specify an execution characte 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'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. +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 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 bd1c16ed79..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: 01/27/2022 +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 for C++20 standard modules in Visual Studio version 16.11 and later. It's still required (along with [`/std:c++latest`](std-specify-language-standard-version.md)) for the experimental Standard library modules. +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/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 01fbb927b2..a0be19b447 100644 --- a/docs/build/reference/fo-object-file-name.md +++ b/docs/build/reference/fo-object-file-name.md @@ -1,10 +1,9 @@ --- title: "/Fo (Object file name)" description: "Reference guide to the Microsoft C++ /Fo (Object file name) compiler option in Visual Studio." -ms.date: 12/12/2022 +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) @@ -12,7 +11,8 @@ Specifies an object (*`.obj`*) file name or directory to be used instead of the ## Syntax -> **`/Fo`***`pathname`* +> **`/Fo"pathname"`**\ +> **`/Fo:[ ]"pathname"`** ## Remarks @@ -26,6 +26,12 @@ To use the **`/Fo`** option to set an output directory for all object files crea ## Example +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: "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 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/fsanitize.md b/docs/build/reference/fsanitize.md index 7fd5128bb7..6e9e8c9439 100644 --- a/docs/build/reference/fsanitize.md +++ b/docs/build/reference/fsanitize.md @@ -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=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/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/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/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 9114479252..61a24b9f5a 100644 --- a/docs/build/reference/guard-enable-control-flow-guard.md +++ b/docs/build/reference/guard-enable-control-flow-guard.md @@ -1,9 +1,8 @@ --- description: "Learn more about: /guard (Enable Control Flow Guard)" title: "/guard (Enable Control Flow Guard)" -ms.date: 09/19/2022 +ms.date: 2/24/2025 f1_keywords: ["/guard", "VC.Project.VCCLCompilerTool.ControlFlowGuard"] -ms.assetid: be495323-f59f-4cf3-a6b6-8ee69e6a19dd --- # `/guard` (Enable Control Flow Guard) @@ -16,7 +15,7 @@ Enable compiler generation of Control Flow Guard security checks. ## 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. @@ -24,7 +23,13 @@ When the **`/guard:cf`** Control Flow Guard (CFG) option is specified, the compi 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. + +To disable the CFG exploit mitigation technique, pass **`/guard:cf-`** to the compiler **`/GUARD:NO`** to the linker. + +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 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`. 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). @@ -33,11 +38,8 @@ Code compiled by using **`/guard:cf`** can be linked to libraries and object fil ### 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 diff --git a/docs/build/reference/headerunit.md b/docs/build/reference/headerunit.md index bd107a2083..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: 02/01/2022 +ms.date: 5/28/2024 f1_keywords: ["/headerUnit"] helpviewer_keywords: ["/headerUnit", "Use header unit IFC"] author: "tylermsft" @@ -14,8 +14,8 @@ Imports a header unit. Tells the compiler where to find the *`.ifc`* file (the b ## 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 @@ -39,7 +39,7 @@ When the compiler comes across `import "file";` or `import ;` this compile - **`/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. Mapping multiple *`header-name`* arguments to a single *`.ifc`* is possible, but it isn't recommended. The contents of the *`.ifc`* are 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. 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-` 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/ilk-name-incremental-database-file.md b/docs/build/reference/ilk-name-incremental-database-file.md index 752535f808..ab1d1d456e 100644 --- a/docs/build/reference/ilk-name-incremental-database-file.md +++ b/docs/build/reference/ilk-name-incremental-database-file.md @@ -1,7 +1,7 @@ --- title: "/ILK (Name incremental database file)" description: "The MSVC linker option /ILK specifies the incremental link database file pathname." -ms.date: 09/07/2022 +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"] --- @@ -16,7 +16,7 @@ The **`/ILK`** linker option tells the linker where to put the *`.ilk`* database ### 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. +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 @@ -25,9 +25,7 @@ The **`/ILK`** linker option tells the linker the path and filename to use for t ### 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 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/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 ce1a75938e..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 are 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). You must now sign your **`/INTEGRITYCHECK`** files by using the Microsoft [Azure Code Signing](https://techcommunity.microsoft.com/t5/security-compliance-and-identity/azure-code-signing-democratizing-trust-for-developers-and/ba-p/3604669) 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/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/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-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 d8bb96a69c..5749d0c236 100644 --- a/docs/build/reference/linker-options.md +++ b/docs/build/reference/linker-options.md @@ -1,26 +1,22 @@ --- title: "MSVC Linker options" description: "A list of the options supported by the Microsoft LINK linker." -ms.date: 09/27/2022 +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). -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) - - [LINK input files](link-input-files.md) - - [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. +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. @@ -33,6 +29,7 @@ You can use the [`comment`](../../preprocessor/comment-c-cpp.md) pragma to speci | [`/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. | @@ -43,7 +40,7 @@ You can use the [`comment`](../../preprocessor/comment-c-cpp.md) pragma to speci | [`/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 P/Invoke stubs that call from managed code into native DLLs. | +| [`/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. | @@ -55,6 +52,7 @@ You can use the [`comment`](../../preprocessor/comment-c-cpp.md) pragma to speci | [`/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. | @@ -75,11 +73,13 @@ You can use the [`comment`](../../preprocessor/comment-c-cpp.md) pragma to speci | [`/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. | @@ -96,6 +96,7 @@ You can use the [`comment`](../../preprocessor/comment-c-cpp.md) pragma to speci | [`/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. | @@ -130,7 +131,8 @@ You can use the [`comment`](../../preprocessor/comment-c-cpp.md) pragma to speci | [`/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 diff --git a/docs/build/reference/linker-property-pages.md b/docs/build/reference/linker-property-pages.md index 84c379aa0b..27a8a52d11 100644 --- a/docs/build/reference/linker-property-pages.md +++ b/docs/build/reference/linker-property-pages.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Linker Property Pages" title: "Linker Property Pages" +description: "Learn more about: Linker Property Pages" ms.date: 09/07/2022 ms.topic: "article" f1_keywords: ["VC.Project.VCLinkerTool.IgnoreImportLibrary", "VC.Project.VCLinkerTool.RegisterOutput", "VC.Project.VCLinkerTool.PerUserRedirection", "VC.Project.VCLinkerTool.LinkLibraryDependencies", "VC.Project.VCLinkerTool.UseLibraryDependencyInputs"] -ms.assetid: 7e7671e5-a35a-4e67-9bdb-661d75c4d11e --- # Linker Property Pages @@ -252,7 +251,7 @@ Specifies total heap allocation size in virtual memory. Default is 1 MB. ([`/ ### Heap Commit Size -Specifies total heap allocation size in physical memory. Default is 4 KB. (`[/HEAP:reserve,commit`](heap-set-heap-size.md)) +Specifies total heap allocation size in physical memory. Default is 4 KB. ([`/HEAP:reserve,commit`](heap-set-heap-size.md)) ### Stack Reserve Size @@ -373,7 +372,7 @@ Partially sign the Windows Metadata. Use [`/WINMDDELAYSIGN`](winmddelaysign-part ### 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 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/makefile-preprocessing.md b/docs/build/reference/makefile-preprocessing.md index ea2e4ada34..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,7 +9,7 @@ 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. @@ -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. @@ -125,7 +125,7 @@ Expressions can use the following operators. The operators of equal precedence a > [!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/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 9c48c9dc54..df8b326f7d 100644 --- a/docs/build/reference/manifestinput-specify-manifest-input.md +++ b/docs/build/reference/manifestinput-specify-manifest-input.md @@ -1,9 +1,8 @@ --- description: "Learn more about: /MANIFESTINPUT (Specify Manifest Input)" title: "/MANIFESTINPUT (Specify Manifest Input)" -ms.date: 09/09/2022 +ms.date: 03/27/2025 f1_keywords: ["VC.Project.VCLinkerTool.ManifestInput"] -ms.assetid: a0b0c21e-1f9b-4d8c-bb3f-178f57fa7f1b --- # /MANIFESTINPUT (Specify Manifest Input) @@ -11,20 +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. -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 a8599cceff..77eceff58e 100644 --- a/docs/build/reference/microsoft-extensions-to-c-and-cpp.md +++ b/docs/build/reference/microsoft-extensions-to-c-and-cpp.md @@ -205,7 +205,6 @@ The C compiler supports the following data declaration and definition features. // 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. These intrinsics don't conform to the standard, because they don't set the `errno` variable. 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/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-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 ba4c2438a9..646e515a1e 100644 --- a/docs/build/reference/nodefaultlib-ignore-libraries.md +++ b/docs/build/reference/nodefaultlib-ignore-libraries.md @@ -1,14 +1,13 @@ --- description: "Learn more about: /NODEFAULTLIB (Ignore libraries)" title: "/NODEFAULTLIB (Ignore libraries)" -ms.date: 09/09/2022 +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) -The **`/NODEFAULTLIB`** linker option tells the linker to remove one or more default libraries from the list of libraries it searches when it resolves external references. +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 @@ -34,11 +33,8 @@ If you use **`/NODEFAULTLIB`** to build your program without the C run-time libr ### To set this linker option in the Visual Studio development environment 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 **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 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/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 e89e033f10..3a182cb84d 100644 --- a/docs/build/reference/permissive-standards-conformance.md +++ b/docs/build/reference/permissive-standards-conformance.md @@ -1,10 +1,9 @@ --- title: "/permissive- (Standards conformance)" description: "Reference guide to the Microsoft C++ /permissive- (Standards conformance) compiler option." -ms.date: 12/14/2022 +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) @@ -33,6 +32,8 @@ 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. +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. + 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. 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/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/running-nmake.md b/docs/build/reference/running-nmake.md index ad7fa7d7b7..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. 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 index 43a316893c..d7a6f2f99c 100644 --- a/docs/build/reference/scandependencies.md +++ b/docs/build/reference/scandependencies.md @@ -2,8 +2,8 @@ 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: "corob-msft" -ms.author: "corob" +author: "tylermsft" +ms.author: "twhitney" f1_keywords: ["/scanDependencies"] helpviewer_keywords: ["/scanDependencies compiler option", "/scanDependencies"] --- @@ -60,10 +60,8 @@ Consider the following sample code: #include import other.module; -import std.core; - +import std; import "t.h"; - import ; int main() {} @@ -83,14 +81,14 @@ The compiler produces a JSON file, *`output.json`*, with content similar to: { "primary-output": "app.obj", "outputs": [ - "C:\\Users\\username\\source\\repos\\app\\app" + "output.json" ], "requires": [ { "logical-name": "other.module" }, { - "logical-name": "std.core" + "logical-name": "std" }, { "logical-name": "t.h", @@ -134,6 +132,7 @@ To report module and header unit dependencies, you must also set the **Configura ## 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)\ diff --git a/docs/build/reference/sourcedependencies-directives.md b/docs/build/reference/sourcedependencies-directives.md index 7f1e9efe38..25cfd5f192 100644 --- a/docs/build/reference/sourcedependencies-directives.md +++ b/docs/build/reference/sourcedependencies-directives.md @@ -9,7 +9,7 @@ helpviewer_keywords: ["/sourceDependencies:directives compiler option", "/source --- # `/sourceDependencies:directives` (List 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. This information can be used by a build system to determine the build order of modules and header units. +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. This option differs from [`/sourceDependencies`](sourcedependencies.md) in the following ways: @@ -59,10 +59,8 @@ Given the following sample code: #include import m; -import std.core; - +import std; import ; - import "t.h"; int main() {} @@ -78,15 +76,16 @@ produces a JSON file *`output.json`* similar to: { "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" ] } } @@ -100,10 +99,11 @@ No *`.ifc`* files are listed in the output because they weren't built. Unlike `/ ## To set this compiler option in Visual Studio -You normally shouldn't set this option yourself in the Visual Studio development environment. It's 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)\ diff --git a/docs/build/reference/sourcedependencies.md b/docs/build/reference/sourcedependencies.md index c0ae01daa1..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: 05/19/2022 +ms.date: 02/23/2024 author: "tylermsft" ms.author: "twhitney" f1_keywords: ["/sourceDependencies"] @@ -65,7 +65,7 @@ where `...` represents your other compiler options. This command line produces a ```JSON { - "Version": "1.1", + "Version": "1.2", "Data": { "Source": "F:\\Sample\\myproject\\modulee.ixx", "ProvidedModule": "ModuleE", @@ -88,10 +88,6 @@ 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" } ] } 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 26f1428da7..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. @@ -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/std-specify-language-standard-version.md b/docs/build/reference/std-specify-language-standard-version.md index 1193548afe..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: 07/07/2022 -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,9 +13,11 @@ 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 @@ -23,16 +25,20 @@ The **`/std`** options are available in Visual Studio 2017 and later. They're us 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). -### C++ standards support +## C++ standards support -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). +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). -**`/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. +> [!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) @@ -40,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 doesn't 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, except for `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. @@ -82,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`. @@ -103,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 4371a12db0..5669fa0e8b 100644 --- a/docs/build/reference/subsystem-specify-subsystem.md +++ b/docs/build/reference/subsystem-specify-subsystem.md @@ -29,7 +29,7 @@ Win32 character-mode application. The operating system provides a console for co **`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). For examples, see the Intel [UEFI Driver and Application Tool Resources](https://www.intel.com/content/www/us/en/architecture-and-technology/unified-extensible-firmware-interface/uefi-driver-and-application-tool-resources.html). The minimum version and default version is 1.0. +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 normally reserved for Windows system components. If [`/DRIVER:WDM`](driver-windows-nt-kernel-mode-driver.md) is specified, `NATIVE` is the default. 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/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 e0a21eadbc..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,7 +86,7 @@ $(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 +### Functions by category | Function | Purpose | Supported | |--|--|--| diff --git a/docs/build/reference/vcpp-directories-property-page.md b/docs/build/reference/vcpp-directories-property-page.md index 524918f380..4b5daa513b 100644 --- a/docs/build/reference/vcpp-directories-property-page.md +++ b/docs/build/reference/vcpp-directories-property-page.md @@ -4,7 +4,6 @@ title: "VC++ Directories Property Page" 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) @@ -22,7 +21,9 @@ To access the **VC++ Directories** property page: 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::: 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). @@ -40,21 +41,25 @@ 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'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. 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". It also shows the current path that each 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::: 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: 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/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.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 5d221e67e7..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,7 +1,7 @@ --- description: "Learn more about: /WX (Treat linker warnings as errors)" title: "/WX (Treat linker warnings as errors)" -ms.date: 09/08/2022 +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 @@ -12,7 +12,8 @@ Specifies whether to treat linker warnings as errors. ## Syntax -> **`/WX`**\[**`:NO`**] +> **`/WX`**\[**`:NO`**]\ +> **`/WX`**\[**`:`***`nnnn`*\[**`,`***`nnnn`*...]] ## Remarks @@ -20,15 +21,23 @@ The **`/WX`** linker option causes no output file to be generated if the linker 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. -By default, **`/WX`** isn't in effect. To treat linker warnings as errors, specify **`/WX`**. **`/WX:NO`** is the same as not specifying **`/WX`**. +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`** 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 more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Select the **Configuration Properties** > **Linker** > **General** property page. +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. In the **Additional Options** edit control, add *`/WX:warnings`*, where *`warnings`* is a comma-separated list of linker warning numbers. -1. Modify the **Treat Linker Warnings as Errors** property. Choose **OK** or **Apply** to save your changes. +1. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -37,4 +46,5 @@ By default, **`/WX`** isn't in effect. To treat linker warnings as errors, speci ## See also [MSVC linker reference](linking.md)\ -[MSVC linker options](linker-options.md) +[MSVC linker options](linker-options.md)\ +[`/WX` compiler option](./compiler-option-warning-level.md) 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 6774cae102..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: 11/08/2022 +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,41 +22,42 @@ Here are the **`/Zc`** compiler options: | Option | Behavior | |--|--| -| [`/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:static_assert`](zc-static-assert.md) | strict handling of `static_assert` (implied by **`/permissive-`**). | -| [`/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: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:zeroSizeArrayNew[-]`](zc-zerosizearraynew.md) | Call member `new`/`delete` for 0-size arrays of objects (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-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-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-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-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 index dfaf7ff2d0..15c36abf13 100644 --- a/docs/build/reference/zc-tlsguards.md +++ b/docs/build/reference/zc-tlsguards.md @@ -1,6 +1,6 @@ --- -description: "Learn more about the /Zc:tlsGuards (Check TLS initialization) compiler option." 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++)"] @@ -29,4 +29,4 @@ The **`/Zc:tlsGuards`** option is new in Visual Studio 2019 version 16.5. This o ## See also -[`/Zc` (Conformance)](zc-conformance.md)\ +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-twophase.md b/docs/build/reference/zc-twophase.md index 61178e9b21..5675256313 100644 --- a/docs/build/reference/zc-twophase.md +++ b/docs/build/reference/zc-twophase.md @@ -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: diff --git a/docs/build/reference/zc-zerosizearraynew.md b/docs/build/reference/zc-zerosizearraynew.md index cbcaedaaea..05abb101da 100644 --- a/docs/build/reference/zc-zerosizearraynew.md +++ b/docs/build/reference/zc-zerosizearraynew.md @@ -1,6 +1,6 @@ --- -description: "Learn more about the /Zc:zeroSizeArrayNew (Call member new/delete on arrays) compiler option." 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++)"] @@ -29,4 +29,4 @@ The **`/Zc:zeroSizeArrayNew`** option may cause a breaking change in code that r ## See also -[`/Zc` (Conformance)](zc-conformance.md)\ +[`/Zc` (Conformance)](zc-conformance.md) 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/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 8eaa69daeb..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 @@ -515,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 @@ -558,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) @@ -620,14 +627,18 @@ items: 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.) + - 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) @@ -694,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 @@ -730,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) @@ -771,7 +788,7 @@ 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 @@ -783,7 +800,9 @@ items: 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:enumTypes (Enable enum type deduction)' + - 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 @@ -853,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 @@ -911,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) @@ -995,6 +1018,8 @@ items: 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) @@ -1005,6 +1030,8 @@ 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) @@ -1039,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) 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 9caa982097..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,9 +1,8 @@ --- -description: "Learn more about: Understanding manifest generation for C/C++ programs" 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 @@ -181,7 +180,7 @@ clean : #^^^^^^^^^^^^^^^^^^^^^^^^^ Change #4. (Add full path if necessary.) ``` -The makefiles now include two files that do the real work,*` makefile.inc`* and *`makefile.target.inc`*. +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: 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-cmakepresets-json-integration). - ![Screenshot of CMake general options screen with Use CMake Presets if available, otherwise use CMakeSettings.json 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 shows 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. @@ -106,11 +113,11 @@ Visual Studio only provides native support for WSL 2 for CMake projects that use 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). -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`. For more information, see [Visual Studio Remote Settings vendor map](cmake-presets-json-reference.md#visual-studio-remote-settings-vendor-map). +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`. @@ -124,11 +131,11 @@ But you may have a MSBuild-based Linux project. 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**: -![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) +:::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 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'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 to learn more, 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 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 1edfba8ac3..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: 05/09/2022 +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 -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, mobile apps, and more. 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. +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 or the Build Tools for Visual Studio and the optional Desktop development with C++ workload. +- 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 **Desktop development with C++** workload (in older versions of Visual Studio, select the **C++ build tools** workload), and choose **Install**. - -When you've installed the tools, there's another tool you'll use to build a C or C++ program on the command line. 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. +- **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'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. +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,11 +54,11 @@ 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 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: @@ -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 Studio 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 Studio. 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 Studio 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,9 +151,9 @@ 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 more source code files, enter them all on the command line: @@ -164,23 +163,23 @@ The compiler outputs a program called *`file1.exe`*. To change the name to *`pro `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. -By default, 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-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 ca7b3fd5ff..2a21f566b6 100644 --- a/docs/build/walkthrough-header-units.md +++ b/docs/build/walkthrough-header-units.md @@ -36,7 +36,7 @@ Header units impose fewer constraints on the required similarities of compiler s 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. +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. diff --git a/docs/build/walkthrough-import-stl-header-units.md b/docs/build/walkthrough-import-stl-header-units.md index 80708ae720..3c2fd2d7e5 100644 --- a/docs/build/walkthrough-import-stl-header-units.md +++ b/docs/build/walkthrough-import-stl-header-units.md @@ -1,6 +1,6 @@ --- -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" +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" @@ -170,7 +170,7 @@ This option is convenient when your project includes many STL header files acros 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. +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. @@ -182,8 +182,8 @@ Follow these steps to create a project that includes two STL libraries: `; - #include ; + #include + #include int main() { @@ -222,4 +222,4 @@ The main consideration for whether to use this approach is the balance between c [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) \ No newline at end of file +[`/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 9a6b533a19..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: -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 c03fee57e9..abb153a846 100644 --- a/docs/build/x64-calling-convention.md +++ b/docs/build/x64-calling-convention.md @@ -1,19 +1,22 @@ --- -title: "x64 calling convention" -description: "Learn about the details of the default x64 calling convention." -ms.date: 05/17/2022 +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*, 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). @@ -25,13 +28,13 @@ Most structures are aligned to their natural alignment. The primary exceptions a ## 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. @@ -99,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. @@ -115,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. @@ -123,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. }; @@ -135,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. }; @@ -166,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) | @@ -174,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. @@ -189,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. @@ -205,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 d1136eff59..fe644a1aa5 100644 --- a/docs/build/x64-software-conventions.md +++ b/docs/build/x64-software-conventions.md @@ -1,7 +1,7 @@ --- description: "Learn more about: x64 ABI conventions" title: "x64 ABI conventions" -ms.date: 04/21/2022 +ms.date: 03/28/2025 helpviewer_keywords: ["x64 coding conventions", "x64 abi", "Visual C++, x64 calling conventions"] --- # Overview of x64 ABI conventions @@ -11,13 +11,16 @@ This topic describes the basic application binary interface (ABI) for x64, the 6 ## x64 calling conventions Two important differences between x86 and x64 are: + - 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. +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: @@ -114,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 @@ -128,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 @@ -143,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 @@ -157,7 +164,9 @@ _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 @@ -209,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 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-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 ce00a770b2..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 (__//__). 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-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-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-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/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/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/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/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/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/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/buffer-manipulation.md b/docs/c-runtime-library/buffer-manipulation.md index 21c4336737..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 @@ -13,17 +12,17 @@ Use these routines to work with areas of memory on a byte-by-byte basis. | 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 | +| [`_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. ## See also -[Universal C runtime routines by category](./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/byte-and-wide-streams.md b/docs/c-runtime-library/byte-and-wide-streams.md index 634f4df7b8..8ef801bf6c 100644 --- a/docs/c-runtime-library/byte-and-wide-streams.md +++ b/docs/c-runtime-library/byte-and-wide-streams.md @@ -4,7 +4,6 @@ description: "An overview of byte streams in the Microsoft C runtime library." ms.date: "11/04/2016" ms.topic: "conceptual" helpviewer_keywords: ["byte streams", "wide streams"] -ms.assetid: 61ef0587-4cbc-4eb8-aae5-4c298dbbc6f9 --- # Byte and wide streams @@ -12,7 +11,7 @@ A byte stream treats a file as a sequence of bytes. Within the program, the stre 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`](./reference/fgetpos.md), and the only reliable way to restore a position obtained this way is by calling [`fsetpos`](./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 diff --git a/docs/c-runtime-library/compatibility.md b/docs/c-runtime-library/compatibility.md index e1c99c1d61..45f753bf02 100644 --- a/docs/c-runtime-library/compatibility.md +++ b/docs/c-runtime-library/compatibility.md @@ -33,6 +33,6 @@ Except as noted within the documentation for specific functions, the UCRT is com | [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 are the CRT supports. | +| [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/control-flags.md b/docs/c-runtime-library/control-flags.md index 69eb347a57..5ba1384bfc 100644 --- a/docs/c-runtime-library/control-flags.md +++ b/docs/c-runtime-library/control-flags.md @@ -8,7 +8,7 @@ ms.assetid: 8dbd24a5-0633-42d1-9771-776db338465f --- # 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 | |---|---| 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-initialization.md b/docs/c-runtime-library/crt-initialization.md index 705348bd86..b2971c1be1 100644 --- a/docs/c-runtime-library/crt-initialization.md +++ b/docs/c-runtime-library/crt-initialization.md @@ -4,7 +4,6 @@ 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 @@ -16,9 +15,9 @@ It's possible, though not recommended, to take advantage of Microsoft-specific l ## 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). -```C +```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 +[`_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 f0eda10039..165f509086 100644 --- a/docs/c-runtime-library/crt-library-features.md +++ b/docs/c-runtime-library/crt-library-features.md @@ -3,7 +3,6 @@ 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", "STL libraries", "Microsoft standard template libraries"] --- # C runtime (CRT) and C++ standard library (STL) `.lib` files @@ -74,7 +73,7 @@ If you're using the **`/clr`** compiler switch, your code will be linked with a 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`](./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. diff --git a/docs/c-runtime-library/crtdbg-map-alloc.md b/docs/c-runtime-library/crtdbg-map-alloc.md index b37fb5729e..b2b1cfec57 100644 --- a/docs/c-runtime-library/crtdbg-map-alloc.md +++ b/docs/c-runtime-library/crtdbg-map-alloc.md @@ -10,7 +10,7 @@ ms.assetid: 435242b8-caea-4063-b765-4a608200312b 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 diff --git a/docs/c-runtime-library/crtdbgflag.md b/docs/c-runtime-library/crtdbgflag.md index 14c2ada306..6617f29a18 100644 --- a/docs/c-runtime-library/crtdbgflag.md +++ b/docs/c-runtime-library/crtdbgflag.md @@ -10,7 +10,7 @@ ms.assetid: 9e7adb47-8ab9-4e19-81d5-e2f237979973 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 along 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 diff --git a/docs/c-runtime-library/data-alignment.md b/docs/c-runtime-library/data-alignment.md index e9c8d32d66..97b03773fb 100644 --- a/docs/c-runtime-library/data-alignment.md +++ b/docs/c-runtime-library/data-alignment.md @@ -1,10 +1,9 @@ --- -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 @@ -14,7 +13,7 @@ The following C run-time functions support data alignment. | 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`](./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). | diff --git a/docs/c-runtime-library/data-type-mappings.md b/docs/c-runtime-library/data-type-mappings.md index 11190a2110..3ae69e97e5 100644 --- a/docs/c-runtime-library/data-type-mappings.md +++ b/docs/c-runtime-library/data-type-mappings.md @@ -18,7 +18,7 @@ For related information, see [Using TCHAR.H Data Types with _MBCS Code](../text/ |---|---|---|---| | `_TCHAR` | **`char`** | **`char`** | **`wchar_t`** | | `_tfinddata_t` | `_finddata_t` | `_finddata_t` | `_wfinddata_t` | -| `_tfinddata64_t` | `__finddata64_t` | `__finddata64_t` | `__wfinddata64_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`** | diff --git a/docs/c-runtime-library/debug-routines.md b/docs/c-runtime-library/debug-routines.md index a6b32a239d..eb6d0ab2dd 100644 --- a/docs/c-runtime-library/debug-routines.md +++ b/docs/c-runtime-library/debug-routines.md @@ -20,7 +20,7 @@ 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`](./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 | |--|--| 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 3ef9ef98fd..049cce0df2 100644 --- a/docs/c-runtime-library/debug.md +++ b/docs/c-runtime-library/debug.md @@ -9,7 +9,7 @@ ms.assetid: a9901568-4846-4731-a404-399d947e2e7a 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 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 b71050dc51..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,10 +2,6 @@ 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: ["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 diff --git a/docs/c-runtime-library/file-handling.md b/docs/c-runtime-library/file-handling.md index 9ff1cf7924..661f7a0fb3 100644 --- a/docs/c-runtime-library/file-handling.md +++ b/docs/c-runtime-library/file-handling.md @@ -1,16 +1,15 @@ --- -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 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`](./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) @@ -18,14 +17,14 @@ These routines operate on files designated by a file descriptor. | 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 | +| [`_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) @@ -33,17 +32,17 @@ These routines operate on files specified by a path or filename. | 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 | +| [`_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) @@ -51,32 +50,30 @@ These routines open files. | 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. | +| [`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`](./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. | +| [`_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](./run-time-routines-by-category.md)\ -[Directory control](./directory-control.md)\ -[System calls](./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/filename-max.md b/docs/c-runtime-library/filename-max.md index 71cd7fb0a3..81d0ddb93a 100644 --- a/docs/c-runtime-library/filename-max.md +++ b/docs/c-runtime-library/filename-max.md @@ -2,7 +2,7 @@ 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 --- diff --git a/docs/c-runtime-library/filename-search-functions.md b/docs/c-runtime-library/filename-search-functions.md index b11a46b69a..fd8726e2d6 100644 --- a/docs/c-runtime-library/filename-search-functions.md +++ b/docs/c-runtime-library/filename-search-functions.md @@ -81,7 +81,7 @@ Functions `_findfirst32i64`, `_findnext32i64`, `_wfindfirst32i64`, and `_wfindne |---|---|---| | `_finddata_t`, `_wfinddata_t` | `__time64_t` | `_fsize_t` | | `_finddata32_t`, `_wfinddata32_t` | `__time32_t` | `_fsize_t` | -| `__finddata64_t`, `__wfinddata64_t` | `__time64_t` | **`__int64`** | +| `__finddata64_t`, `_wfinddata64_t` | `__time64_t` | **`__int64`** | | `_finddata32i64_t`, `_wfinddata32i64_t` | `__time32_t` | **`__int64`** | | `_finddata64i32_t`, `_wfinddata64i32_t` | `__time64_t` | `_fsize_t` | 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 69a51ce7ce..7f4ac7bc98 100644 --- a/docs/c-runtime-library/floating-point-support.md +++ b/docs/c-runtime-library/floating-point-support.md @@ -11,7 +11,9 @@ The Universal C Runtime library (UCRT) provides many integral and floating-point 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 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. +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. @@ -79,7 +81,7 @@ Previous 16-bit versions of Microsoft C/C++ and Microsoft Visual C++ supported t | [`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 | +| [`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 | diff --git a/docs/c-runtime-library/fopen-max-sys-open.md b/docs/c-runtime-library/fopen-max-sys-open.md index 5fb01fb982..8076924089 100644 --- a/docs/c-runtime-library/fopen-max-sys-open.md +++ b/docs/c-runtime-library/fopen-max-sys-open.md @@ -2,7 +2,7 @@ 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 --- 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 bf5994d104..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 @@ -3,7 +3,6 @@ description: "Learn more about: Format specification fields: scanf and wscanf fu 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"] --- # Format specification fields: `scanf` and `wscanf` functions 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 361c713b02..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 @@ -65,7 +65,7 @@ Integer types such as `short`, `int`, `long`, `long long`, and their `unsigned` | **`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`. | +| **`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: diff --git a/docs/c-runtime-library/freeentry-usedentry.md b/docs/c-runtime-library/freeentry-usedentry.md index c516f182ef..e6dd6248f6 100644 --- a/docs/c-runtime-library/freeentry-usedentry.md +++ b/docs/c-runtime-library/freeentry-usedentry.md @@ -2,7 +2,7 @@ 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 --- diff --git a/docs/c-runtime-library/fseek-lseek-constants.md b/docs/c-runtime-library/fseek-lseek-constants.md index bcde2121b5..8218c3ace8 100644 --- a/docs/c-runtime-library/fseek-lseek-constants.md +++ b/docs/c-runtime-library/fseek-lseek-constants.md @@ -2,7 +2,7 @@ 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 --- diff --git a/docs/c-runtime-library/heap-constants.md b/docs/c-runtime-library/heap-constants.md index efe4319949..71ae99a468 100644 --- a/docs/c-runtime-library/heap-constants.md +++ b/docs/c-runtime-library/heap-constants.md @@ -2,7 +2,7 @@ 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 --- diff --git a/docs/c-runtime-library/heap-maxreq.md b/docs/c-runtime-library/heap-maxreq.md index 168783f841..e0b2918230 100644 --- a/docs/c-runtime-library/heap-maxreq.md +++ b/docs/c-runtime-library/heap-maxreq.md @@ -2,7 +2,7 @@ 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 --- diff --git a/docs/c-runtime-library/heapset.md b/docs/c-runtime-library/heapset.md index 98b435fbb4..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,7 +8,6 @@ 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` @@ -47,7 +46,7 @@ In addition, if an error occurs, **`_heapset`** sets `errno` to `ENOSYS`. 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 doesn't 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 diff --git a/docs/c-runtime-library/huge-val-huge.md b/docs/c-runtime-library/huge-val-huge.md index 26ee64947d..98eaf2b2ea 100644 --- a/docs/c-runtime-library/huge-val-huge.md +++ b/docs/c-runtime-library/huge-val-huge.md @@ -6,7 +6,7 @@ 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 --- @@ -20,7 +20,7 @@ ms.assetid: 3f044b45-02cd-46b2-b1de-87fd0441dd6a ## 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 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 8fa090cdd9..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,12 +2,12 @@ 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_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 @@ -40,10 +40,9 @@ These functions and function macros are used to implement the CRT and the C++ St |---| | `__acrt_iob_func` | | `__AdjustPointer` | -| `_assert` | | `__BuildCatchObject` | | `__BuildCatchObjectHelper` | -| `__C_specific_handler` | +| [`__C_specific_handler`](/windows/win32/devnotes/--c-specific-handler2) | | `_calloc_base` | | `_chkesp` | | `__chkstk` | @@ -125,27 +124,27 @@ These functions and function macros are used to implement the CRT and the C++ St | `__CxxRegisterExceptionObject` | | `_CxxThrowException` | | `__CxxUnregisterExceptionObject` | -| `__daylight` | -| `_dclass` | +| [`_dclass`](./reference/floating-point-primitives.md) | | `__DestructExceptionObject` | | [`__dllonexit`](./dllonexit.md) | | `__doserrno` | | `_dosmaperr` | -| `_dpcomp` | -| `_dsign` | -| `__dstbias` | -| `_dtest` | +| [`_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`](./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` | -| `_fdpcomp` | -| `_fdsign` | -| `_fdtest` | +| [`_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` | @@ -188,10 +187,10 @@ These functions and function macros are used to implement the CRT and the C++ St | [`___lc_collate_cp_func`](./lc-collate-cp-func.md) | | [`___lc_locale_name_func`](./lc-locale-name-func.md) | | `__lconv_init` | -| `_ldclass` | -| `_ldpcomp` | -| `_ldsign` | -| `_ldtest` | +| [`_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` | @@ -261,9 +260,9 @@ These functions and function macros are used to implement the CRT and the C++ St | `__p__wcmdln` | | `__p__wenviron` | | `__p__wpgmptr` | -| `_pctype` | +| [`_pctype`](./pctype-pwctype-wctype-mbctype-mbcasemap.md) | | [`__pctype_func`](./pctype-func.md) | -| `_pwctype` | +| [`_pwctype`](./pctype-pwctype-wctype-mbctype-mbcasemap.md) | | `__pwctype_func` | | `__pxcptinfoptrs` | | `_query_app_type` | @@ -336,7 +335,6 @@ These functions and function macros are used to implement the CRT and the C++ St | `_W_Getmonths` | | `_W_Getnames` | | `_W_Gettnames` | -| `_wassert` | | `_Wcsftime` | | `__wcsncnt` | | [`__wgetmainargs`](./getmainargs-wgetmainargs.md) | diff --git a/docs/c-runtime-library/internal-set-app-type.md b/docs/c-runtime-library/internal-set-app-type.md index 6f3526048d..9faaf4a49e 100644 --- a/docs/c-runtime-library/internal-set-app-type.md +++ b/docs/c-runtime-library/internal-set-app-type.md @@ -12,7 +12,7 @@ ms.assetid: f0ac0f4d-70e6-4e96-9e43-eb9d1515490c --- # `__set_app_type` -Sets the current application type. +Sets the current application type. This internal function is obsolete. ## Syntax diff --git a/docs/c-runtime-library/iob.md b/docs/c-runtime-library/iob.md index 6029c1d1f8..9341f6b617 100644 --- a/docs/c-runtime-library/iob.md +++ b/docs/c-runtime-library/iob.md @@ -1,14 +1,13 @@ --- 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_ENTRIES", "STDIO/_IOB_ENTRIES"] helpviewer_keywords: ["_iob global variable", "iob global variable"] -ms.assetid: 008ed376-8078-4bbd-bc6c-0677c63d0ff1 --- # `_iob` @@ -22,8 +21,12 @@ FILE _iob[_IOB_ENTRIES]; ## Remarks -`_IOB_ENTRIES` is defined as 3 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](./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 ed95473112..749a96439b 100644 --- a/docs/c-runtime-library/is-isw-routines.md +++ b/docs/c-runtime-library/is-isw-routines.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: is, isw Routines" title: "is, isw Routines" +description: "Learn more about: is, isw Routines" ms.date: 01/11/2022 helpviewer_keywords: ["is routines", "isw routines"] --- @@ -15,7 +15,7 @@ helpviewer_keywords: ["is routines", "isw routines"] [`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) + [`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)\ diff --git a/docs/c-runtime-library/ismbc-routines.md b/docs/c-runtime-library/ismbc-routines.md index 6de251be77..7c7a33362c 100644 --- a/docs/c-runtime-library/ismbc-routines.md +++ b/docs/c-runtime-library/ismbc-routines.md @@ -1,45 +1,40 @@ --- -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 Each `_ismbc` routine tests a given multibyte character `c` for a particular condition. -- [`_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) +- [`_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`](./reference/getmbcp.md) or [`_setmbcp`](./reference/setmbcp.md), respectively. +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. +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. | +| [`_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** @@ -47,18 +42,18 @@ The following routines are specific to code page 932. | 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. | +| [`_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 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. +`_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](./character-classification.md)\ -[`is`, `isw` routines](./is-isw-routines.md)\ -[`_ismbb` routines](./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/language-strings.md b/docs/c-runtime-library/language-strings.md index c68c721c29..99b9af3a15 100644 --- a/docs/c-runtime-library/language-strings.md +++ b/docs/c-runtime-library/language-strings.md @@ -6,7 +6,7 @@ helpviewer_keywords: ["language strings"] --- # Language strings -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). +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 @@ -82,7 +82,7 @@ The Microsoft C run-time library implementation also supports these language str ## See also -- [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) +- [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 26ce3e89fc..21d5dd5640 100644 --- a/docs/c-runtime-library/lc-codepage-func.md +++ b/docs/c-runtime-library/lc-codepage-func.md @@ -6,7 +6,7 @@ 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-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 --- diff --git a/docs/c-runtime-library/lc-collate-cp-func.md b/docs/c-runtime-library/lc-collate-cp-func.md index 7b3da7427e..e507776555 100644 --- a/docs/c-runtime-library/lc-collate-cp-func.md +++ b/docs/c-runtime-library/lc-collate-cp-func.md @@ -6,7 +6,7 @@ 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-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 --- diff --git a/docs/c-runtime-library/lc-locale-name-func.md b/docs/c-runtime-library/lc-locale-name-func.md index 4817722305..0fbf0416f2 100644 --- a/docs/c-runtime-library/lc-locale-name-func.md +++ b/docs/c-runtime-library/lc-locale-name-func.md @@ -6,7 +6,7 @@ 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-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 --- diff --git a/docs/c-runtime-library/link-options.md b/docs/c-runtime-library/link-options.md index 33a73b92de..7f27f9a178 100644 --- a/docs/c-runtime-library/link-options.md +++ b/docs/c-runtime-library/link-options.md @@ -1,27 +1,26 @@ --- -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 -The CRT lib directory includes several small object files that enable specific CRT features without any code change. These object files are called "link options" since you only 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`](./fmode.md). | +| `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). | +| `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. | +| `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). | +| `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. | @@ -32,4 +31,4 @@ CLR pure mode versions of these objects are deprecated in Visual Studio 2015 and ## See also -- [C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./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/locale-categories.md b/docs/c-runtime-library/locale-categories.md index dde72bbca3..891ebbf4d1 100644 --- a/docs/c-runtime-library/locale-categories.md +++ b/docs/c-runtime-library/locale-categories.md @@ -2,7 +2,7 @@ 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 --- diff --git a/docs/c-runtime-library/locale.md b/docs/c-runtime-library/locale.md index f7ced3c342..5801ca774e 100644 --- a/docs/c-runtime-library/locale.md +++ b/docs/c-runtime-library/locale.md @@ -1,63 +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/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](./locale-categories.md). +*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 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). +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). +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` | +| [`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`](./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. +> 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](./internationalization.md)\ -[Universal C runtime routines by category](./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 3efcf2aed8..19562f13ef 100644 --- a/docs/c-runtime-library/lock.md +++ b/docs/c-runtime-library/lock.md @@ -1,14 +1,13 @@ --- -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` @@ -20,7 +19,7 @@ Acquires a multi-thread lock. ## Syntax ```cpp -void __cdecl _lock +void __cdecl _lock( int locknum ); ``` diff --git a/docs/c-runtime-library/locking-constants.md b/docs/c-runtime-library/locking-constants.md index b6ccc86e45..3951399044 100644 --- a/docs/c-runtime-library/locking-constants.md +++ b/docs/c-runtime-library/locking-constants.md @@ -2,7 +2,7 @@ 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 --- diff --git a/docs/c-runtime-library/math-constants.md b/docs/c-runtime-library/math-constants.md index cd7110f018..61b129659a 100644 --- a/docs/c-runtime-library/math-constants.md +++ b/docs/c-runtime-library/math-constants.md @@ -2,7 +2,7 @@ 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 --- diff --git a/docs/c-runtime-library/math-error-constants.md b/docs/c-runtime-library/math-error-constants.md index 6b598ed388..78d4219229 100644 --- a/docs/c-runtime-library/math-error-constants.md +++ b/docs/c-runtime-library/math-error-constants.md @@ -2,7 +2,7 @@ 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 --- 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 538f6fc375..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 @@ -6,7 +6,7 @@ api_name: ["___mb_cur_max_l_func", "__p___mb_cur_max", "___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_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 --- diff --git a/docs/c-runtime-library/new-operator-crt.md b/docs/c-runtime-library/new-operator-crt.md index 161e0cee8b..c5273af0c4 100644 --- a/docs/c-runtime-library/new-operator-crt.md +++ b/docs/c-runtime-library/new-operator-crt.md @@ -5,7 +5,6 @@ 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 --- diff --git a/docs/c-runtime-library/nolock-functions.md b/docs/c-runtime-library/nolock-functions.md index 2f99d4430c..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 -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). +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`](./reference/fclose-nolock.md) - -[`_fflush_nolock`](./reference/fflush-nolock.md) - -[`_fgetc_nolock`, `_fgetwc_nolock`](./reference/fgetc-nolock-fgetwc-nolock.md) - -[`_fread_nolock`](./reference/fread-nolock.md) - -[`_fseek_nolock`, `_fseeki64_nolock`](./reference/fseek-nolock-fseeki64-nolock.md) - -[`_ftell_nolock`, `_ftelli64_nolock`](./reference/ftell-nolock-ftelli64-nolock.md) - -[`_fwrite_nolock`](./reference/fwrite-nolock.md) - -[`_getc_nolock`, `_getwc_nolock`](./reference/getc-nolock-getwc-nolock.md) - -[`_getch_nolock`, `_getwch_nolock`](./reference/getch-nolock-getwch-nolock.md) - -[`_getchar_nolock`, `_getwchar_nolock`](./reference/getchar-nolock-getwchar-nolock.md) - -[`_getche_nolock`, `_getwche_nolock`](./reference/getche-nolock-getwche-nolock.md) - -[`_getdcwd_nolock`, `_wgetdcwd_nolock`](./reference/getdcwd-nolock-wgetdcwd-nolock.md) - -[`_putc_nolock`, `_putwc_nolock`](./reference/putc-nolock-putwc-nolock.md) - -[`_putch_nolock`, `_putwch_nolock`](./reference/putch-nolock-putwch-nolock.md) - -[`_putchar_nolock`, `_putwchar_nolock`](./reference/putchar-nolock-putwchar-nolock.md) - -[`_ungetc_nolock`, `_ungetwc_nolock`](./reference/ungetc-nolock-ungetwc-nolock.md) - -[`_ungetch_nolock`, `_ungetwch_nolock`](./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](./input-and-output.md)\ -[Universal C runtime routines by category](./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/p-commode.md b/docs/c-runtime-library/p-commode.md index 6a5ad340aa..3367ece1ce 100644 --- a/docs/c-runtime-library/p-commode.md +++ b/docs/c-runtime-library/p-commode.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/p-fmode.md b/docs/c-runtime-library/p-fmode.md index 27a57b4cac..ce214aea1b 100644 --- a/docs/c-runtime-library/p-fmode.md +++ b/docs/c-runtime-library/p-fmode.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/pctype-func.md b/docs/c-runtime-library/pctype-func.md index 60e628f381..e3918dc32f 100644 --- a/docs/c-runtime-library/pctype-func.md +++ b/docs/c-runtime-library/pctype-func.md @@ -6,7 +6,7 @@ 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-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 --- diff --git a/docs/c-runtime-library/printf-p-positional-parameters.md b/docs/c-runtime-library/printf-p-positional-parameters.md index cb4ed9f1a4..4237a034ea 100644 --- a/docs/c-runtime-library/printf-p-positional-parameters.md +++ b/docs/c-runtime-library/printf-p-positional-parameters.md @@ -2,9 +2,6 @@ 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 --- diff --git a/docs/c-runtime-library/rand-max.md b/docs/c-runtime-library/rand-max.md index 4fa2115b4e..532c58038c 100644 --- a/docs/c-runtime-library/rand-max.md +++ b/docs/c-runtime-library/rand-max.md @@ -2,7 +2,7 @@ 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"] --- # `RAND_MAX` diff --git a/docs/c-runtime-library/reference/abort.md b/docs/c-runtime-library/reference/abort.md index 10cc8e6f7b..436a39de91 100644 --- a/docs/c-runtime-library/reference/abort.md +++ b/docs/c-runtime-library/reference/abort.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: abort" title: "abort" +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"] @@ -14,7 +14,7 @@ helpviewer_keywords: ["aborting current process", "abort function", "processes, 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 @@ -48,7 +48,7 @@ If the Windows error reporting handler isn't invoked, then **`abort`** calls [`_ 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** @@ -71,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 ) { 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 1f3fedc12e..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,19 +1,20 @@ --- -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_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. 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 ```C @@ -66,18 +67,20 @@ These functions validate their parameters. If *`path`* is `NULL` or *`mode`* doe By 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 + +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 | +| `tchar.h` function | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | |---|---|---|---| -| `_taccess_s` | **`_access_s`** | **`_access_s`** | **`_waccess_s`** | +| `_taccess_s` | `_access_s` | `_access_s` | `_waccess_s` | ## Requirements | Routine | Required header | Optional header | |---|---|---| -| **`_access_s`** | \ | \ | -| **`_waccess_s`** | \ or \ | \ | +| **`_access_s`** | `` | `` | +| **`_waccess_s`** | `` or `` | `` | ## Example diff --git a/docs/c-runtime-library/reference/access-waccess.md b/docs/c-runtime-library/reference/access-waccess.md index b6c08cc8bf..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_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 @@ -66,7 +67,7 @@ This function validates its parameters. If *`path`* is `NULL` or *`mode`* doesn' By 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 | |---|---|---|---| @@ -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 ) { diff --git a/docs/c-runtime-library/reference/aligned-free-dbg.md b/docs/c-runtime-library/reference/aligned-free-dbg.md index 335eb7bcd7..1ef9d5fe97 100644 --- a/docs/c-runtime-library/reference/aligned-free-dbg.md +++ b/docs/c-runtime-library/reference/aligned-free-dbg.md @@ -35,7 +35,7 @@ The **`_aligned_free_dbg`** function is a debug version of the [`_aligned_free`] 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're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and their debug versions, 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 diff --git a/docs/c-runtime-library/reference/aligned-malloc-dbg.md b/docs/c-runtime-library/reference/aligned-malloc-dbg.md index 3bd869b597..c9a59fa438 100644 --- a/docs/c-runtime-library/reference/aligned-malloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-malloc-dbg.md @@ -51,7 +51,7 @@ A pointer to the memory block that was allocated or `NULL` if the operation fail **`_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're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and their debug versions, 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 diff --git a/docs/c-runtime-library/reference/aligned-msize-dbg.md b/docs/c-runtime-library/reference/aligned-msize-dbg.md index 59c29a626b..ef2623a5e2 100644 --- a/docs/c-runtime-library/reference/aligned-msize-dbg.md +++ b/docs/c-runtime-library/reference/aligned-msize-dbg.md @@ -47,7 +47,7 @@ The *`alignment`* and *`offset`* values must be the same as the values passed to 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're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and their debug versions, 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 diff --git a/docs/c-runtime-library/reference/aligned-msize.md b/docs/c-runtime-library/reference/aligned-msize.md index 0a788ac236..62782ee251 100644 --- a/docs/c-runtime-library/reference/aligned-msize.md +++ b/docs/c-runtime-library/reference/aligned-msize.md @@ -43,7 +43,7 @@ Returns the size (in bytes) as an unsigned integer. 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`* 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. 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 1ba74be1cb..3eaa602cfb 100644 --- a/docs/c-runtime-library/reference/aligned-offset-malloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-offset-malloc-dbg.md @@ -59,9 +59,9 @@ A pointer to the memory block that was allocated or `NULL` if the operation fail 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're 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 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 1d15ec8793..b9292dae92 100644 --- a/docs/c-runtime-library/reference/aligned-offset-realloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-offset-realloc-dbg.md @@ -61,7 +61,7 @@ Like [`_aligned_offset_malloc`](aligned-offset-malloc.md), **`_aligned_offset_re 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're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and their debug versions, 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 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 5cb27e2cfe..34046b47a6 100644 --- a/docs/c-runtime-library/reference/aligned-offset-recalloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-offset-recalloc-dbg.md @@ -63,7 +63,7 @@ Line number in the source file where the realloc operation was requested or `NUL 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're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and their debug versions, 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 diff --git a/docs/c-runtime-library/reference/aligned-realloc-dbg.md b/docs/c-runtime-library/reference/aligned-realloc-dbg.md index 046ed087e9..02f8a69c49 100644 --- a/docs/c-runtime-library/reference/aligned-realloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-realloc-dbg.md @@ -59,7 +59,7 @@ It's an error to reallocate memory and change the alignment of a block. 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're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and their debug versions, 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 diff --git a/docs/c-runtime-library/reference/aligned-recalloc-dbg.md b/docs/c-runtime-library/reference/aligned-recalloc-dbg.md index 40b3a04bb3..41d2154689 100644 --- a/docs/c-runtime-library/reference/aligned-recalloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-recalloc-dbg.md @@ -63,7 +63,7 @@ It's an error to reallocate memory and change the alignment of a block. 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're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and their debug versions, 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 diff --git a/docs/c-runtime-library/reference/and-eq.md b/docs/c-runtime-library/reference/and-eq.md index eedfaa1408..b8844704b3 100644 --- a/docs/c-runtime-library/reference/and-eq.md +++ b/docs/c-runtime-library/reference/and-eq.md @@ -5,7 +5,7 @@ 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 --- diff --git a/docs/c-runtime-library/reference/and.md b/docs/c-runtime-library/reference/and.md index 29068d62c8..efa2cca286 100644 --- a/docs/c-runtime-library/reference/and.md +++ b/docs/c-runtime-library/reference/and.md @@ -1,13 +1,12 @@ --- -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` @@ -16,7 +15,6 @@ An alternative to the && operator. ## Syntax ```C - #define and && ``` 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 2067b8fa6a..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 @@ -42,14 +42,14 @@ Because the `_ASSERTE` macro specifies the failed expression, and `_ASSERT_EXPR` 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. 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 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. 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 4601d51fb1..116c8c986c 100644 --- a/docs/c-runtime-library/reference/assert-macro-assert-wassert.md +++ b/docs/c-runtime-library/reference/assert-macro-assert-wassert.md @@ -68,7 +68,7 @@ As a consequence of the above behavior, a dialog box is always displayed followi | `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. diff --git a/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md b/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md index 02b797f39a..b7ce5af41b 100644 --- a/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md +++ b/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md @@ -1,14 +1,13 @@ --- 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_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` 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 917b291e28..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 @@ -53,7 +53,7 @@ These functions convert a character string to an integer value (**`atoi`** and * 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. 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 bb6f755930..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 @@ -54,7 +54,7 @@ The input string is a sequence of characters that can be interpreted as a numeri 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. diff --git a/docs/c-runtime-library/reference/bitand.md b/docs/c-runtime-library/reference/bitand.md index 5735dced0c..0701824a21 100644 --- a/docs/c-runtime-library/reference/bitand.md +++ b/docs/c-runtime-library/reference/bitand.md @@ -1,13 +1,12 @@ --- -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` @@ -16,7 +15,6 @@ 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 f0c717a7a5..8f2aaf236d 100644 --- a/docs/c-runtime-library/reference/bitor.md +++ b/docs/c-runtime-library/reference/bitor.md @@ -1,13 +1,12 @@ --- -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` @@ -16,7 +15,6 @@ An alternative to the `|` operator. ## Syntax ```C - #define bitor | ``` 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 5c63829355..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 @@ -54,8 +54,8 @@ int main() ``` ```Output -byteswap of 102030405060708 = 807060504030201 -byteswap of 1020304 = 4030201 +byteswap of 0102030405060708 = 0807060504030201 +byteswap of 01020304 = 04030201 ``` ## See also diff --git a/docs/c-runtime-library/reference/calloc-dbg.md b/docs/c-runtime-library/reference/calloc-dbg.md index b480d041b1..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,7 +8,6 @@ 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` @@ -37,7 +36,7 @@ Requested size of each memory block (bytes). *`blockType`*\ Requested type of memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -For information about the allocation block types and how they're 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`. @@ -65,7 +64,7 @@ On successful completion, this function returns a pointer to the user portion of **`_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 and the debug version, 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 @@ -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 ); } diff --git a/docs/c-runtime-library/reference/calloc.md b/docs/c-runtime-library/reference/calloc.md index 1f52cec60d..eda1a8195f 100644 --- a/docs/c-runtime-library/reference/calloc.md +++ b/docs/c-runtime-library/reference/calloc.md @@ -50,7 +50,7 @@ _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, **`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). @@ -96,4 +96,4 @@ Allocated 40 long integers [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/cgets-s-cgetws-s.md b/docs/c-runtime-library/reference/cgets-s-cgetws-s.md index 8709404d4c..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,6 +1,6 @@ --- -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"] @@ -8,7 +8,6 @@ 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` @@ -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 ); diff --git a/docs/c-runtime-library/reference/chdir-wchdir.md b/docs/c-runtime-library/reference/chdir-wchdir.md index 1ceeb72ce8..d95f085350 100644 --- a/docs/c-runtime-library/reference/chdir-wchdir.md +++ b/docs/c-runtime-library/reference/chdir-wchdir.md @@ -78,7 +78,6 @@ For more compatibility information, see [Compatibility](../compatibility.md). int main( int argc, char *argv[] ) { - if(_chdir( argv[1] ) ) { switch (errno) diff --git a/docs/c-runtime-library/reference/chmod-wchmod.md b/docs/c-runtime-library/reference/chmod-wchmod.md index 327b83aee7..eb98e7289c 100644 --- a/docs/c-runtime-library/reference/chmod-wchmod.md +++ b/docs/c-runtime-library/reference/chmod-wchmod.md @@ -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" ); diff --git a/docs/c-runtime-library/reference/compl.md b/docs/c-runtime-library/reference/compl.md index af061c570c..290367a95d 100644 --- a/docs/c-runtime-library/reference/compl.md +++ b/docs/c-runtime-library/reference/compl.md @@ -6,7 +6,7 @@ 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 --- diff --git a/docs/c-runtime-library/reference/controlfp-s.md b/docs/c-runtime-library/reference/controlfp-s.md index d955dfb42e..8de3df8b7c 100644 --- a/docs/c-runtime-library/reference/controlfp-s.md +++ b/docs/c-runtime-library/reference/controlfp-s.md @@ -1,7 +1,7 @@ --- 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_type: ["DLLExport"] @@ -75,16 +75,23 @@ _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'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. -On the ARM and x64 architectures, 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 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 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`. +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 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. diff --git a/docs/c-runtime-library/reference/cputs-cputws.md b/docs/c-runtime-library/reference/cputs-cputws.md index cf01b13749..5ffe5fe412 100644 --- a/docs/c-runtime-library/reference/cputs-cputws.md +++ b/docs/c-runtime-library/reference/cputs-cputws.md @@ -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"; diff --git a/docs/c-runtime-library/reference/crtcheckmemory.md b/docs/c-runtime-library/reference/crtcheckmemory.md index df206aa190..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,7 +8,6 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CrtCheckMemory", "_CrtCheckMemory"] helpviewer_keywords: ["_CrtCheckMemory function", "CrtCheckMemory function"] -ms.assetid: 457cc72e-60fd-4177-ab5c-6ae26a420765 --- # `_CrtCheckMemory` @@ -17,7 +16,6 @@ Confirms the integrity of the memory blocks allocated in the debug heap (debug v ## Syntax ```C - int _CrtCheckMemory( void ); ``` @@ -37,7 +35,7 @@ Because this function returns `TRUE` or `FALSE`, it can be passed to one of the _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 diff --git a/docs/c-runtime-library/reference/crtdbgbreak.md b/docs/c-runtime-library/reference/crtdbgbreak.md index b3763e3cfa..057be6cfa3 100644 --- a/docs/c-runtime-library/reference/crtdbgbreak.md +++ b/docs/c-runtime-library/reference/crtdbgbreak.md @@ -28,7 +28,7 @@ There's no return value. 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 diff --git a/docs/c-runtime-library/reference/crtdbgreport-crtdbgreportw.md b/docs/c-runtime-library/reference/crtdbgreport-crtdbgreportw.md index 25218f6335..10ec08e428 100644 --- a/docs/c-runtime-library/reference/crtdbgreport-crtdbgreportw.md +++ b/docs/c-runtime-library/reference/crtdbgreport-crtdbgreportw.md @@ -80,7 +80,7 @@ The following table lists the available choices for the report mode or modes and | `_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. diff --git a/docs/c-runtime-library/reference/crtdoforallclientobjects.md b/docs/c-runtime-library/reference/crtdoforallclientobjects.md index 9db4a22cfe..fdf8480c26 100644 --- a/docs/c-runtime-library/reference/crtdoforallclientobjects.md +++ b/docs/c-runtime-library/reference/crtdoforallclientobjects.md @@ -37,7 +37,7 @@ The **`_CrtDoForAllClientObjects`** function searches the heap's linked list for 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](../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. @@ -55,5 +55,5 @@ For more compatibility information, see [Compatibility](../compatibility.md). [Debug routines](../debug-routines.md)\ [`_CrtSetDbgFlag`](crtsetdbgflag.md)\ -[Heap state reporting functions](/visualstudio/debugger/crt-debug-heap-details)\ +[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 bbcc1210b6..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"] @@ -16,7 +16,6 @@ Dumps all the memory blocks in the debug heap when a memory leak has occurred (d ## Syntax ```C - int _CrtDumpMemoryLeaks( void ); ``` @@ -34,7 +33,7 @@ The **`_CrtDumpMemoryLeaks`** function determines whether a memory leak has occu 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 diff --git a/docs/c-runtime-library/reference/crtgetallochook.md b/docs/c-runtime-library/reference/crtgetallochook.md index f37adc40c3..44feae4b2f 100644 --- a/docs/c-runtime-library/reference/crtgetallochook.md +++ b/docs/c-runtime-library/reference/crtgetallochook.md @@ -28,7 +28,7 @@ Returns the currently defined allocation hook function. **`_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 diff --git a/docs/c-runtime-library/reference/crtgetdumpclient.md b/docs/c-runtime-library/reference/crtgetdumpclient.md index df55f8a428..5fb865da19 100644 --- a/docs/c-runtime-library/reference/crtgetdumpclient.md +++ b/docs/c-runtime-library/reference/crtgetdumpclient.md @@ -28,7 +28,7 @@ Returns the current dump routine. 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 diff --git a/docs/c-runtime-library/reference/crtgetreporthook.md b/docs/c-runtime-library/reference/crtgetreporthook.md index 54f4867696..f1782c2533 100644 --- a/docs/c-runtime-library/reference/crtgetreporthook.md +++ b/docs/c-runtime-library/reference/crtgetreporthook.md @@ -28,7 +28,7 @@ Returns the current client-defined reporting function. **`_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 diff --git a/docs/c-runtime-library/reference/crtismemoryblock.md b/docs/c-runtime-library/reference/crtismemoryblock.md index 12a1f2e07a..367d8155be 100644 --- a/docs/c-runtime-library/reference/crtismemoryblock.md +++ b/docs/c-runtime-library/reference/crtismemoryblock.md @@ -60,7 +60,7 @@ _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 diff --git a/docs/c-runtime-library/reference/crtisvalidheappointer.md b/docs/c-runtime-library/reference/crtisvalidheappointer.md index 40d24affff..8ed29e0417 100644 --- a/docs/c-runtime-library/reference/crtisvalidheappointer.md +++ b/docs/c-runtime-library/reference/crtisvalidheappointer.md @@ -40,7 +40,7 @@ Because this function returns `TRUE` or `FALSE`, it can be passed to one of the _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 diff --git a/docs/c-runtime-library/reference/crtisvalidpointer.md b/docs/c-runtime-library/reference/crtisvalidpointer.md index 2ced5ae22b..202506f2c0 100644 --- a/docs/c-runtime-library/reference/crtisvalidpointer.md +++ b/docs/c-runtime-library/reference/crtisvalidpointer.md @@ -49,7 +49,7 @@ Because this function returns `TRUE` or `FALSE`, it can be passed to one of the _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 diff --git a/docs/c-runtime-library/reference/crtmemcheckpoint.md b/docs/c-runtime-library/reference/crtmemcheckpoint.md index d1d20858d9..9f5043ab22 100644 --- a/docs/c-runtime-library/reference/crtmemcheckpoint.md +++ b/docs/c-runtime-library/reference/crtmemcheckpoint.md @@ -33,7 +33,7 @@ The **`_CrtMemCheckpoint`** function creates a snapshot of the current state of 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](../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. diff --git a/docs/c-runtime-library/reference/crtmemdifference.md b/docs/c-runtime-library/reference/crtmemdifference.md index 6b783c68b9..2424df0b3f 100644 --- a/docs/c-runtime-library/reference/crtmemdifference.md +++ b/docs/c-runtime-library/reference/crtmemdifference.md @@ -48,7 +48,7 @@ The **`_CrtMemDifference`** function compares *`oldState`* and *`newState`* and 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 @@ -63,4 +63,4 @@ For more compatibility information, see [Compatibility](../compatibility.md). ## See also [Debug routines](../debug-routines.md)\ -[`_crtDbgFlag`](../crtdbgflag.md)\ +[`_crtDbgFlag`](../crtdbgflag.md) diff --git a/docs/c-runtime-library/reference/crtmemdumpallobjectssince.md b/docs/c-runtime-library/reference/crtmemdumpallobjectssince.md index 215b33d999..0f3b1f0fdd 100644 --- a/docs/c-runtime-library/reference/crtmemdumpallobjectssince.md +++ b/docs/c-runtime-library/reference/crtmemdumpallobjectssince.md @@ -35,7 +35,7 @@ The **`_CrtMemDumpAllObjectsSince`** function dumps the debug header information 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 diff --git a/docs/c-runtime-library/reference/crtmemdumpstatistics.md b/docs/c-runtime-library/reference/crtmemdumpstatistics.md index 1015da2d9f..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,7 +8,6 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CrtMemDumpStatistics", "_CrtMemDumpStatistics"] helpviewer_keywords: ["_CrtMemDumpStatistics function", "CrtMemDumpStatistics function"] -ms.assetid: 27b9d731-3184-4a2d-b9a7-6566ab28a9fe --- # `_CrtMemDumpStatistics` @@ -33,7 +32,7 @@ The **`_CrtMemDumpStatistics`** function dumps the debug header information for 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 @@ -47,4 +46,4 @@ For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Debug routines](../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 c433723ed3..e9c58f7c24 100644 --- a/docs/c-runtime-library/reference/crtreportblocktype.md +++ b/docs/c-runtime-library/reference/crtreportblocktype.md @@ -1,14 +1,13 @@ --- -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` @@ -19,7 +18,7 @@ Returns the block type/subtype associated with a given debug heap block pointer. ```C int _CrtReportBlockType( const void * pBlock -}; +); ``` ### Parameters @@ -35,7 +34,7 @@ When passed a valid debug heap pointer, the **`_CrtReportBlockType`** function r 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're 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 diff --git a/docs/c-runtime-library/reference/crtsetallochook.md b/docs/c-runtime-library/reference/crtsetallochook.md index f17713841f..9219339783 100644 --- a/docs/c-runtime-library/reference/crtsetallochook.md +++ b/docs/c-runtime-library/reference/crtsetallochook.md @@ -53,7 +53,7 @@ When the hook function wants the main allocation process to continue as if the t 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. diff --git a/docs/c-runtime-library/reference/crtsetbreakalloc.md b/docs/c-runtime-library/reference/crtsetbreakalloc.md index 0e402b09e0..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,7 +8,6 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CrtSetBreakAlloc", "_CrtSetBreakAlloc"] helpviewer_keywords: ["CrtSetBreakAlloc function", "_CrtSetBreakAlloc function"] -ms.assetid: 33bfc6af-a9ea-405b-a29f-1c2d4d9880a1 --- # `_CrtSetBreakAlloc` @@ -37,7 +36,7 @@ Returns the previous object allocation order number that had a breakpoint set. 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 @@ -99,4 +98,4 @@ int main( ) ## See also -[Debug routines](../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 c9ac357052..e65cc7cb4e 100644 --- a/docs/c-runtime-library/reference/crtsetdbgflag.md +++ b/docs/c-runtime-library/reference/crtsetdbgflag.md @@ -40,7 +40,7 @@ The **`_CrtSetDbgFlag`** function allows the application to control how the debu 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](/visualstudio/debugger/crt-debug-heap-details). +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 | |---|---|---| @@ -117,7 +117,7 @@ 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, use a bitwise "and" (`&`) of the variable with the bitwise "not" (`~`) of the bitmask. diff --git a/docs/c-runtime-library/reference/crtsetdebugfillthreshold.md b/docs/c-runtime-library/reference/crtsetdebugfillthreshold.md index bd91d7fa57..b7ce8b7bbb 100644 --- a/docs/c-runtime-library/reference/crtsetdebugfillthreshold.md +++ b/docs/c-runtime-library/reference/crtsetdebugfillthreshold.md @@ -1,14 +1,13 @@ --- 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` @@ -38,58 +37,36 @@ 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`** | \ | +| **`_CrtSetDebugFillThreshold`** | `` | This function is Microsoft-specific. For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/crtsetdumpclient.md b/docs/c-runtime-library/reference/crtsetdumpclient.md index 220fadaa08..8d2590b289 100644 --- a/docs/c-runtime-library/reference/crtsetdumpclient.md +++ b/docs/c-runtime-library/reference/crtsetdumpclient.md @@ -45,7 +45,7 @@ The *`userPortion`* argument is a pointer to the beginning of the user data port 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 diff --git a/docs/c-runtime-library/reference/crtsetreportfile.md b/docs/c-runtime-library/reference/crtsetreportfile.md index 35b801e080..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,7 +8,6 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CrtSetReportFile", "_CrtSetReportFile"] helpviewer_keywords: ["CrtSetReportFile function", "_CrtSetReportFile function"] -ms.assetid: 3126537e-511b-44af-9c1c-0605265eabc4 --- # `_CrtSetReportFile` @@ -91,4 +90,4 @@ The console isn't supported in Universal Windows Platform (UWP) apps. The standa ## See also -[Debug routines](../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 7b71a5eaa7..1938344e34 100644 --- a/docs/c-runtime-library/reference/crtsetreporthook.md +++ b/docs/c-runtime-library/reference/crtsetreporthook.md @@ -47,7 +47,7 @@ where *`reportType`* is the debug report type (`_CRT_WARN`, `_CRT_ERROR`, or `_C 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. 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 ff9fcbd2f5..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 @@ -109,7 +109,7 @@ Zero if successful. If there's a failure due to an invalid parameter, the invali 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. diff --git a/docs/c-runtime-library/reference/cxxthrowexception.md b/docs/c-runtime-library/reference/cxxthrowexception.md index 1bad3b4dd0..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,7 +8,6 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CxxThrowException", "_CxxThrowException"] helpviewer_keywords: ["_CxxThrowException function", "CxxThrowException function"] -ms.assetid: 0b90bef5-b7d2-46e0-88e2-59e531e01a4d --- # `_CxxThrowException` @@ -18,7 +17,7 @@ Builds the exception record and calls the runtime environment to start processin ```C extern "C" void __stdcall _CxxThrowException( - void* pExceptionObject + void* pExceptionObject, _ThrowInfo* pThrowInfo ); ``` 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 9fab3a0583..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,7 +8,6 @@ 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` @@ -67,7 +66,7 @@ If these functions can't allocate enough memory, they set *`buffer`* to `NULL` a 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 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](/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 @@ -88,7 +87,7 @@ For more compatibility information, see [Compatibility](../compatibility.md). ```C // crt_dupenv_s_dbg.c -#include +#include #include int main( void ) 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 e0d4242db2..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,6 +1,6 @@ --- -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"] @@ -8,7 +8,6 @@ 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` @@ -89,7 +88,7 @@ For more compatibility information, see [Compatibility](../compatibility.md). ```C // crt_dupenv_s.c -#include +#include int main( void ) { diff --git a/docs/c-runtime-library/reference/exit-exit-exit.md b/docs/c-runtime-library/reference/exit-exit-exit.md index 1ad98c4dc5..bcec154714 100644 --- a/docs/c-runtime-library/reference/exit-exit-exit.md +++ b/docs/c-runtime-library/reference/exit-exit-exit.md @@ -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 diff --git a/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md b/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md index b2d84ff608..bf7a2e2893 100644 --- a/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md +++ b/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md @@ -8,7 +8,6 @@ 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` @@ -79,5 +78,5 @@ For more compatibility information, see [Compatibility](../compatibility.md). ## See also [Alphabetical function reference](crt-alphabetical-function-reference.md)\ -[`exp`, `expf`, `expl`](exp-expf.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 8e826cebfc..5998a4195c 100644 --- a/docs/c-runtime-library/reference/expand-dbg.md +++ b/docs/c-runtime-library/reference/expand-dbg.md @@ -57,7 +57,7 @@ The **`_expand_dbg`** function is a debug version of the _[`expand`](expand.md) 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're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and debug versions, 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 *`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`. diff --git a/docs/c-runtime-library/reference/expand.md b/docs/c-runtime-library/reference/expand.md index c3199ec7ce..dfcbe00e56 100644 --- a/docs/c-runtime-library/reference/expand.md +++ b/docs/c-runtime-library/reference/expand.md @@ -48,7 +48,7 @@ The **`_expand`** function changes the size of a previously allocated memory blo > [!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`*. -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](../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`. diff --git a/docs/c-runtime-library/reference/fclose-nolock.md b/docs/c-runtime-library/reference/fclose-nolock.md index ca205e0355..b03860a277 100644 --- a/docs/c-runtime-library/reference/fclose-nolock.md +++ b/docs/c-runtime-library/reference/fclose-nolock.md @@ -1,6 +1,6 @@ --- -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"] @@ -8,11 +8,10 @@ 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` -Closes a stream without thread-locking. +Closes a stream without locking. ## Syntax diff --git a/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md b/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md index 652e9aaf6b..89145b12af 100644 --- a/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md +++ b/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md @@ -8,7 +8,6 @@ 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` @@ -93,4 +92,4 @@ For more compatibility information, see [Compatibility](../compatibility.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)\ +[`abs`, `labs`, `llabs`, `_abs64`](abs-labs-llabs-abs64.md) diff --git a/docs/c-runtime-library/reference/fegetround-fesetround2.md b/docs/c-runtime-library/reference/fegetround-fesetround2.md index 8a6a274159..d771b3c7d4 100644 --- a/docs/c-runtime-library/reference/fegetround-fesetround2.md +++ b/docs/c-runtime-library/reference/fegetround-fesetround2.md @@ -8,7 +8,6 @@ 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` @@ -18,10 +17,7 @@ Gets or sets the current floating-point rounding mode. ```C int fegetround(void); - -int fesetround( - int round_mode -); +int fesetround(int round_mode); ``` ### Parameters @@ -51,30 +47,29 @@ The default behavior of `FE_TONEAREST` is to round results midway between repres 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`. - - Return values from standard library mathematical 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). +> [!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`** | \ | \ | +| **`fegetround`**, **`fesetround`** | `` | `` | -For more compatibility information, see [Compatibility](../compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## See also diff --git a/docs/c-runtime-library/reference/fflush-nolock.md b/docs/c-runtime-library/reference/fflush-nolock.md index 2934639b30..4c83497bc9 100644 --- a/docs/c-runtime-library/reference/fflush-nolock.md +++ b/docs/c-runtime-library/reference/fflush-nolock.md @@ -1,6 +1,6 @@ --- -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"] @@ -8,11 +8,10 @@ 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` -Flushes a stream without locking the thread. +Flushes a stream without locking. ## Syntax 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 6ef2d4d806..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,6 +1,6 @@ --- -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"] @@ -8,11 +8,10 @@ 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` -Reads a character from a stream without locking the thread. +Reads a character from a stream without locking. ## Syntax diff --git a/docs/c-runtime-library/reference/findfirst-functions.md b/docs/c-runtime-library/reference/findfirst-functions.md index d34d13c777..dcfbffe363 100644 --- a/docs/c-runtime-library/reference/findfirst-functions.md +++ b/docs/c-runtime-library/reference/findfirst-functions.md @@ -72,7 +72,7 @@ intptr_t _wfindfirst64i32( Target file specification (can include wildcard characters). *`fileinfo`*\ -File information buffer. +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 @@ -101,7 +101,7 @@ These functions use various forms of the **`_finddata_t`** structure for the *`f 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 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`**, **`_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 behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/floating-point-ordering.md b/docs/c-runtime-library/reference/floating-point-ordering.md index ece44b97be..acdf45961d 100644 --- a/docs/c-runtime-library/reference/floating-point-ordering.md +++ b/docs/c-runtime-library/reference/floating-point-ordering.md @@ -1,6 +1,6 @@ --- -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"] @@ -43,7 +43,7 @@ int isunordered( ); /* C-only macro */ ``` -```C++ +```cpp template inline bool isgreater( FloatingType1 x, diff --git a/docs/c-runtime-library/reference/fma-fmaf-fmal.md b/docs/c-runtime-library/reference/fma-fmaf-fmal.md index 7838e4e7d1..5c1d6f5f4b 100644 --- a/docs/c-runtime-library/reference/fma-fmaf-fmal.md +++ b/docs/c-runtime-library/reference/fma-fmaf-fmal.md @@ -1,6 +1,6 @@ --- 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"] @@ -12,7 +12,7 @@ ms.assetid: 584a6037-da1e-4e86-9f0c-97aae86de0c0 --- # `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 @@ -63,7 +63,7 @@ The value to add. ## 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: 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 47072fb31b..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,7 +1,7 @@ --- title: "fopen_s, _wfopen_s" description: "Describes the API for `fopen_s` and `_wfopen_s`" -ms.date: 05/18/2022 +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_type: ["DLLExport"] @@ -31,10 +31,10 @@ 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. @@ -55,7 +55,7 @@ Zero if successful; an error code on failure. For more information about these e 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. @@ -111,14 +111,14 @@ When the **`"r+"`**, **`"w+"`**, or **`"a+"`** access type is specified, both re 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. | +| **`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. 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. +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 (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). @@ -133,8 +133,8 @@ For more information about using text and binary modes in Unicode and multibyte | **`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. | +| **`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. | @@ -150,21 +150,27 @@ Valid characters for the *`mode`* string used in **`fopen_s`** and [`_fdopen`](f | **`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` | +| **`t`** | `_O_TEXT` (translated) | | **`c`** | None | | **`n`** | None | -| **`S`** | `_O_SEQUENTIAL` | -| **`R`** | `_O_RANDOM` | -| **`t`** | `_O_SHORTLIVED` | +| **`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`**, 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. +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 | C++ header | diff --git a/docs/c-runtime-library/reference/fopen-wfopen.md b/docs/c-runtime-library/reference/fopen-wfopen.md index 2a7036a39a..22d44f2421 100644 --- a/docs/c-runtime-library/reference/fopen-wfopen.md +++ b/docs/c-runtime-library/reference/fopen-wfopen.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: fopen, _wfopen" title: "fopen, _wfopen" -ms.date: 05/18/2022 +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_type: ["DLLExport"] @@ -42,9 +42,9 @@ For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr` ## 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, 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. +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 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). @@ -60,7 +60,7 @@ Allowed values for **`ccs`** encoding are `UNICODE`, **`UTF-8`**, and **`UTF-16L 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, then any byte order mark (BOM) 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 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). @@ -77,7 +77,7 @@ The following table summarizes the modes that are used for various **`ccs`** fla Files opened for writing in Unicode mode have a BOM written to them automatically. -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`** will then reopen the file by using write-only access. (This behavior 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 @@ -106,7 +106,7 @@ In addition to the earlier values, the following characters can be appended to * | *`mode`* modifier | Translation mode | |--|--| -| **`t`** | Open in text (translated) 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 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. @@ -127,8 +127,8 @@ The following options can be appended to *`mode`* to specify more behaviors. | **`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. | +| **`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");` | 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. @@ -136,16 +136,17 @@ Valid characters for the *`mode`* string that is used in **`fopen`** and **`_fdo | 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` ) | +| **`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` | +| **`t`** | `_O_TEXT` (translated) | | **`x`** | `_O_EXCL` | | **`c`** | None | | **`n`** | None | +| **`N`** | `_O_NOINHERIT` | | **`S`** | `_O_SEQUENTIAL` | | **`R`** | `_O_RANDOM` | | **`T`** | `_O_SHORTLIVED` | @@ -156,6 +157,13 @@ Valid characters for the *`mode`* string that is used in **`fopen`** and **`_fdo 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. +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. + +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 | 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 184d2fc5e9..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 @@ -73,12 +75,14 @@ The versions of these functions with the **`_l`** suffix are identical except th > > 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` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +| `tchar.h` function | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | |---|---|---|---| -| **`_ftprintf`** | **`fprintf`** | **`fprintf`** | **`fwprintf`** | -| **`_ftprintf_l`** | **`_fprintf_l`** | **`_fprintf_l`** | **`_fwprintf_l`** | +| `_ftprintf` | `fprintf` | `fprintf` | `fwprintf` | +| `_ftprintf_l` | `_fprintf_l` | `_fprintf_l` | `_fwprintf_l` | For more information, see [Format specification syntax](../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 877bf4a16d..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 @@ -73,12 +75,14 @@ The versions of these functions with the `_l` suffix are identical except that t 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 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` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +| `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`** | +| `_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 specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). @@ -86,8 +90,8 @@ For more information, see [Format specification syntax](../format-specification- | Function | Required header | |---|---| -| **`_fprintf_p`**, **`_fprintf_p_l`** | \ | -| **`_fwprintf_p`**, **`_fwprintf_p_l`** | \ or \ | +| `_fprintf_p`, `_fprintf_p_l` | `` | +| `_fwprintf_p`, `_fwprintf_p_l` | `` or `` | For more compatibility information, see [Compatibility](../compatibility.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 9cdfdff5fc..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,18 +1,20 @@ --- -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 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 ```C @@ -69,17 +71,18 @@ The versions of these functions with the **`_l`** suffix are identical except th > [!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). 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 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` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +| `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`** | +| `_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 specification syntax](../format-specification-syntax-printf-and-wprintf-functions.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 b5e7c99d06..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,6 +1,6 @@ --- -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"] @@ -8,11 +8,10 @@ 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` -Writes a character to a stream without locking the thread. +Writes a character to a stream without locking. ## Syntax diff --git a/docs/c-runtime-library/reference/fread-nolock-s2.md b/docs/c-runtime-library/reference/fread-nolock-s2.md index e2d09bd776..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_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fread_nolock_s", "stdio/_fread_nolock_s"] -ms.assetid: 5badb9ab-11df-4e17-8162-30bda2a4572e --- # `_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](../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 diff --git a/docs/c-runtime-library/reference/fread-nolock.md b/docs/c-runtime-library/reference/fread-nolock.md index 33a87a6e60..44f32e0cac 100644 --- a/docs/c-runtime-library/reference/fread-nolock.md +++ b/docs/c-runtime-library/reference/fread-nolock.md @@ -1,6 +1,6 @@ --- -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"] @@ -8,11 +8,10 @@ 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` -Reads data from a stream, without locking other threads. +Reads data from a stream without locking. ## Syntax diff --git a/docs/c-runtime-library/reference/free-dbg.md b/docs/c-runtime-library/reference/free-dbg.md index c431251202..49f863d551 100644 --- a/docs/c-runtime-library/reference/free-dbg.md +++ b/docs/c-runtime-library/reference/free-dbg.md @@ -39,7 +39,7 @@ The **`_free_dbg`** function is a debug version of the [`free`](free.md) functio 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're 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 the debug version, 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 diff --git a/docs/c-runtime-library/reference/free.md b/docs/c-runtime-library/reference/free.md index 3bbb2120b1..0e9f412d04 100644 --- a/docs/c-runtime-library/reference/free.md +++ b/docs/c-runtime-library/reference/free.md @@ -34,7 +34,7 @@ If an error occurs in freeing the memory, `errno` is set with information from t 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). diff --git a/docs/c-runtime-library/reference/freea.md b/docs/c-runtime-library/reference/freea.md index 7b383907e5..1e0aab4f41 100644 --- a/docs/c-runtime-library/reference/freea.md +++ b/docs/c-runtime-library/reference/freea.md @@ -41,7 +41,7 @@ If an error occurs in freeing the memory, `errno` is set with information from t 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'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](/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). diff --git a/docs/c-runtime-library/reference/freopen-wfreopen.md b/docs/c-runtime-library/reference/freopen-wfreopen.md index 7f4f99c2dc..79b74adb3f 100644 --- a/docs/c-runtime-library/reference/freopen-wfreopen.md +++ b/docs/c-runtime-library/reference/freopen-wfreopen.md @@ -1,6 +1,6 @@ --- -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"] @@ -141,4 +141,4 @@ This will go to the file 'freopen.out' [`_fileno`](fileno.md)\ [`fopen`, `_wfopen`](fopen-wfopen.md)\ [`_open`, `_wopen`](open-wopen.md)\ -[`_setmode`](setmode.md)\ +[`_setmode`](setmode.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 093ec08bc1..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,6 +1,6 @@ --- -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"] @@ -8,11 +8,10 @@ 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` -Moves the file pointer to a specified location. +Moves the file pointer to a specified location without locking. ## Syntax diff --git a/docs/c-runtime-library/reference/fsopen-wfsopen.md b/docs/c-runtime-library/reference/fsopen-wfsopen.md index 2a36f1e840..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_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` @@ -69,18 +68,24 @@ When a file is opened with the **"`a`"** or **"`a+`"** access type, all write op |---|---| | **`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. | -| **`S`** | Specifies that caching is optimized for, but not restricted to, sequential access from disk. | +| **`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. | -| **`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. | +| **`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`** 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. | 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 c89869526a..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 @@ -22,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, @@ -73,7 +73,7 @@ If *`fd`* refers to a device, the **`st_atime`**, **`st_ctime`**, **`st_mtime`** 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. The lower bound of the date range for all these functions is Midnight, January 1, 1970. +**`_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. 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 1ea776edcf..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,6 +1,6 @@ --- -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"] @@ -8,11 +8,10 @@ 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` -Gets the current position of a file pointer, without locking the thread. +Gets the current position of a file pointer without locking. ## Syntax 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 40e95fd7f6..e611447e0b 100644 --- a/docs/c-runtime-library/reference/fullpath-dbg-wfullpath-dbg.md +++ b/docs/c-runtime-library/reference/fullpath-dbg-wfullpath-dbg.md @@ -63,7 +63,7 @@ Each function returns a pointer to a buffer containing the absolute path name (* 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 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](/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 @@ -84,4 +84,4 @@ For more compatibility information, see [Compatibility](../compatibility.md). [File handling](../file-handling.md)\ [`_fullpath`, `_wfullpath`](fullpath-wfullpath.md)\ -[Debug versions of heap allocation functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions) +[Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md) diff --git a/docs/c-runtime-library/reference/fwide.md b/docs/c-runtime-library/reference/fwide.md index f21511e106..71113cfe48 100644 --- a/docs/c-runtime-library/reference/fwide.md +++ b/docs/c-runtime-library/reference/fwide.md @@ -1,14 +1,13 @@ --- -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` @@ -19,7 +18,7 @@ Unimplemented. ```C int fwide( FILE *stream, - int mode; + int mode ); ``` diff --git a/docs/c-runtime-library/reference/fwrite-nolock.md b/docs/c-runtime-library/reference/fwrite-nolock.md index 524a968125..1f72d29198 100644 --- a/docs/c-runtime-library/reference/fwrite-nolock.md +++ b/docs/c-runtime-library/reference/fwrite-nolock.md @@ -1,6 +1,6 @@ --- -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"] @@ -8,11 +8,10 @@ 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` -Writes data to a stream, without locking the thread. +Writes data to a stream without locking. ## Syntax diff --git a/docs/c-runtime-library/reference/get-daylight.md b/docs/c-runtime-library/reference/get-daylight.md index 5778e6cd40..6cba686071 100644 --- a/docs/c-runtime-library/reference/get-daylight.md +++ b/docs/c-runtime-library/reference/get-daylight.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/reference/get-timezone.md b/docs/c-runtime-library/reference/get-timezone.md index 017c4d09ca..9b273ddf65 100644 --- a/docs/c-runtime-library/reference/get-timezone.md +++ b/docs/c-runtime-library/reference/get-timezone.md @@ -33,7 +33,7 @@ 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](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EINVAL`. 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 d825ec6c7b..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,6 +1,6 @@ --- -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"] @@ -8,11 +8,10 @@ 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` -Reads a character from a stream. +Reads a character from a stream without locking. ## Syntax diff --git a/docs/c-runtime-library/reference/getch-getwch.md b/docs/c-runtime-library/reference/getch-getwch.md index f4108094b5..82d45dd775 100644 --- a/docs/c-runtime-library/reference/getch-getwch.md +++ b/docs/c-runtime-library/reference/getch-getwch.md @@ -1,7 +1,7 @@ --- 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_type: ["DLLExport"] @@ -29,7 +29,7 @@ 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. 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)). +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 so are thread-safe. For non-locking versions, see [`_getch_nolock`, `_getwch_nolock`](getch-nolock-getwch-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 8c9b4a8a32..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,6 +1,6 @@ --- 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"] @@ -8,11 +8,10 @@ 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` -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). 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 aaf8bcf23a..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` -Reads a character from standard input. +Reads a character from the standard input without locking. ## Syntax 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 821f722335..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,6 +1,6 @@ --- 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"] @@ -8,11 +8,10 @@ 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` -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). 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 d156f0fd4a..1a9d43dc61 100644 --- a/docs/c-runtime-library/reference/getcwd-dbg-wgetcwd-dbg.md +++ b/docs/c-runtime-library/reference/getcwd-dbg-wgetcwd-dbg.md @@ -60,7 +60,7 @@ For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr` 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 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](/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 mapping @@ -81,4 +81,4 @@ For more compatibility information, see [Compatibility](../compatibility.md). [`_getcwd`, `_wgetcwd`](getcwd-wgetcwd.md)\ [Directory control](../directory-control.md)\ -[Debug versions of heap allocation functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions) +[Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.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 1ecae36fed..4f3d1b56f7 100644 --- a/docs/c-runtime-library/reference/getdcwd-dbg-wgetdcwd-dbg.md +++ b/docs/c-runtime-library/reference/getdcwd-dbg-wgetdcwd-dbg.md @@ -63,7 +63,7 @@ Returns a pointer to *`buffer`*. A `NULL` return value indicates an error, and ` 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 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](/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 @@ -84,4 +84,4 @@ For more compatibility information, see [Compatibility](../compatibility.md). [`_getdcwd`, `_wgetdcwd`](getdcwd-wgetdcwd.md)\ [Directory control](../directory-control.md)\ -[Debug versions of heap allocation functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions) +[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 1ee8358edb..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,7 +8,6 @@ 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` diff --git a/docs/c-runtime-library/reference/gmtime-gmtime32-gmtime64.md b/docs/c-runtime-library/reference/gmtime-gmtime32-gmtime64.md index 4baf83e371..1d0656b3f7 100644 --- a/docs/c-runtime-library/reference/gmtime-gmtime32-gmtime64.md +++ b/docs/c-runtime-library/reference/gmtime-gmtime32-gmtime64.md @@ -1,7 +1,7 @@ --- title: "gmtime, _gmtime32, _gmtime64" description: "API reference for gmtime, _gmtime32, and _gmtime64, which convert a time_t value." -ms.date: "10/27/2020" +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_type: ["DLLExport"] @@ -54,9 +54,6 @@ These functions validate their parameters. If *`sourceTime`* is a `NULL` pointer 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 behavior, see [Global state in the CRT](../global-state.md). ## Requirements 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 7db288694f..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,7 +1,7 @@ --- 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_type: ["DLLExport"] @@ -56,9 +56,6 @@ The first two error conditions invoke the invalid parameter handler, as describe 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. -> [!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 . - Each of the structure fields is of type **`int`**, as shown in the following table. | Field | Description | diff --git a/docs/c-runtime-library/reference/heapchk.md b/docs/c-runtime-library/reference/heapchk.md index 589d119aef..4e77c83690 100644 --- a/docs/c-runtime-library/reference/heapchk.md +++ b/docs/c-runtime-library/reference/heapchk.md @@ -1,6 +1,6 @@ --- -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"] @@ -8,7 +8,6 @@ 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` @@ -36,7 +35,7 @@ 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 doesn't 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 behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/heapmin.md b/docs/c-runtime-library/reference/heapmin.md index ffee2908c1..f5f5e5671a 100644 --- a/docs/c-runtime-library/reference/heapmin.md +++ b/docs/c-runtime-library/reference/heapmin.md @@ -1,6 +1,6 @@ --- -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"] @@ -8,7 +8,6 @@ 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` @@ -28,7 +27,7 @@ For more information about this and other return codes, see [`errno`, `_doserrno ## Remarks -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`. +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 behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/initterm-initterm-e.md b/docs/c-runtime-library/reference/initterm-initterm-e.md index 27ef43bc02..3063706706 100644 --- a/docs/c-runtime-library/reference/initterm-initterm-e.md +++ b/docs/c-runtime-library/reference/initterm-initterm-e.md @@ -25,8 +25,8 @@ void __cdecl _initterm( ); int __cdecl _initterm_e( - PVFV *, - PVFV * + PIFV *, + PIFV * ); ``` 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 02dded213e..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,14 +1,13 @@ --- -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_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` @@ -54,7 +53,7 @@ The behavior of **`islower`** and **`_islower_l`** is undefined if *`c`* isn't E | 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`** | +| **`_istlower_l`** | `_islower_l` | [`_ismbclower_l`](ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) | **`_liswlower_l`** | ## Remarks @@ -64,10 +63,10 @@ By default, this function's global state is scoped to the application. To change | Routine | Required header | |---|---| -| **`islower`** | \ | -| **`iswlower`** | \ or \ | -| **`_islower_l`** | \ | -| **`_swlower_l`** | \ or \ | +| **`islower`** | `` | +| **`iswlower`** | `` or `` | +| **`_islower_l`** | `` | +| **`_swlower_l`** | `` or `` | For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/itoa-itow.md b/docs/c-runtime-library/reference/itoa-itow.md index 48046135b6..1f03714208 100644 --- a/docs/c-runtime-library/reference/itoa-itow.md +++ b/docs/c-runtime-library/reference/itoa-itow.md @@ -8,7 +8,6 @@ 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` @@ -137,7 +136,7 @@ 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; } ``` diff --git a/docs/c-runtime-library/reference/kbhit.md b/docs/c-runtime-library/reference/kbhit.md index e4f1f9cfb7..3d89e65caa 100644 --- a/docs/c-runtime-library/reference/kbhit.md +++ b/docs/c-runtime-library/reference/kbhit.md @@ -1,6 +1,6 @@ --- -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"] @@ -8,7 +8,6 @@ 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,7 +19,6 @@ Checks the console for keyboard input. ## Syntax ```C - int _kbhit( void ); ``` 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 475f466870..4ff277f7b0 100644 --- a/docs/c-runtime-library/reference/log-logf-log10-log10f.md +++ b/docs/c-runtime-library/reference/log-logf-log10-log10f.md @@ -122,9 +122,9 @@ Log base 2 of 65536.000000 is 16.000000 ## See also -[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)\ +[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 9463d7bc03..4b73bb4062 100644 --- a/docs/c-runtime-library/reference/log1p-log1pf-log1pl2.md +++ b/docs/c-runtime-library/reference/log1p-log1pf-log1pl2.md @@ -1,14 +1,13 @@ --- 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_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` @@ -17,25 +16,14 @@ 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 @@ -68,9 +56,9 @@ The **`log1p`** functions may be more accurate than using `log(x + 1)` when *`x` 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](../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 behavior, see [Global state in the CRT](../global-state.md). @@ -78,8 +66,8 @@ By default, this function's global state is scoped to the application. To change | Function | C header | C++ header | |---|---|---| -| **`log1p`**, **`log1pf`**, **`log1pl`** | \ | \ | -| **`log1p`** macro | \ | | +| **`log1p`**, **`log1pf`**, **`log1pl`** | `` | `` | +| **`log1p`** macro | `` | | For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/longjmp.md b/docs/c-runtime-library/reference/longjmp.md index e94b1110c1..da78b65d11 100644 --- a/docs/c-runtime-library/reference/longjmp.md +++ b/docs/c-runtime-library/reference/longjmp.md @@ -1,6 +1,6 @@ --- -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"] @@ -8,7 +8,6 @@ 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` @@ -75,5 +74,5 @@ See the example for [`_fpreset`](fpreset.md). ## See also -[Process and environment control](../process-and-environment-control.md) +[Process and environment control](../process-and-environment-control.md)\ [`setjmp`](setjmp.md) diff --git a/docs/c-runtime-library/reference/malloc-dbg.md b/docs/c-runtime-library/reference/malloc-dbg.md index be297575b4..9de32b3c52 100644 --- a/docs/c-runtime-library/reference/malloc-dbg.md +++ b/docs/c-runtime-library/reference/malloc-dbg.md @@ -53,7 +53,7 @@ On successful completion, this function returns a pointer to the user portion of **`_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're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and debug versions, 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 diff --git a/docs/c-runtime-library/reference/malloc.md b/docs/c-runtime-library/reference/malloc.md index c9590f0be7..959948becb 100644 --- a/docs/c-runtime-library/reference/malloc.md +++ b/docs/c-runtime-library/reference/malloc.md @@ -90,7 +90,7 @@ The startup code uses **`malloc`** to allocate storage for the **`_environ`**, * 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)`. 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). diff --git a/docs/c-runtime-library/reference/malloca.md b/docs/c-runtime-library/reference/malloca.md index 9953a91657..56b67ffeb9 100644 --- a/docs/c-runtime-library/reference/malloca.md +++ b/docs/c-runtime-library/reference/malloca.md @@ -1,7 +1,7 @@ --- -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"] @@ -38,7 +38,7 @@ If *`size`* is greater than `_ALLOCA_S_THRESHOLD`, then **`_malloca`** attempts 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 SEH exception filter expression: **`__except`** (`_malloca ()` ) +- Windows SEH exception filter expression: **`__except`** (`_malloca ()`) - Windows SEH final exception handler: **`__finally`** {`_malloca ()` } diff --git a/docs/c-runtime-library/reference/mbbtype-mbbtype-l.md b/docs/c-runtime-library/reference/mbbtype-mbbtype-l.md index abff8af776..d3e9461cbe 100644 --- a/docs/c-runtime-library/reference/mbbtype-mbbtype-l.md +++ b/docs/c-runtime-library/reference/mbbtype-mbbtype-l.md @@ -50,9 +50,9 @@ The locale to use. |---|---|---|---| | 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 | +| 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 (any value except 0x20 - 0x7E, 0xA1 - 0xDF, 0x81 - 0x9F, 0xE0 - 0xFC | +| 1 | Valid trail byte | `_MBC_ILLEGAL` (-1) | Invalid character: not trailing (0x00 - 0x3F, 0x7F, 0xFD, 0xFE, 0xFF) | ## Remarks diff --git a/docs/c-runtime-library/reference/mbrtowc.md b/docs/c-runtime-library/reference/mbrtowc.md index b8634e50a7..7c64576e18 100644 --- a/docs/c-runtime-library/reference/mbrtowc.md +++ b/docs/c-runtime-library/reference/mbrtowc.md @@ -1,14 +1,13 @@ --- -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_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbrtowc"] helpviewer_keywords: ["mbrtowc function"] -ms.assetid: a1e87fcc-6de0-4ca1-bf26-508d28490286 --- # `mbrtowc` @@ -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; } 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 89e0fa5454..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 @@ -84,7 +84,7 @@ By default, this function's global state is scoped to the application. To change | 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) | +| `_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) | 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 903e87992a..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,14 +1,13 @@ --- -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_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` @@ -90,14 +89,14 @@ By default, this function's global state is scoped to the application. To change | 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` | +| `_tcsnset_s_l` | `_strnset_s_l` | **`_mbsnbset_s_l`** | `_wcsnset_s_l` | ## Requirements | Routine | Required header | |---|---| -| **`_mbsnbset_s`** | \ | -| **`_mbsnbset_s_l`** | \ | +| **`_mbsnbset_s`** | `` | +| **`_mbsnbset_s_l`** | `` | For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/memcpy-wmemcpy.md b/docs/c-runtime-library/reference/memcpy-wmemcpy.md index 6f9ff121ff..4572322b81 100644 --- a/docs/c-runtime-library/reference/memcpy-wmemcpy.md +++ b/docs/c-runtime-library/reference/memcpy-wmemcpy.md @@ -1,6 +1,6 @@ --- -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"] @@ -8,7 +8,6 @@ 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` @@ -49,14 +48,14 @@ The value of *`dest`*. **`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 **`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 @@ -92,4 +91,4 @@ See [`memmove`](memmove-wmemmove.md) for a sample of how to use **`memcpy`**. [`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/memmove-wmemmove.md b/docs/c-runtime-library/reference/memmove-wmemmove.md index 4cce4c066c..00c3f732e4 100644 --- a/docs/c-runtime-library/reference/memmove-wmemmove.md +++ b/docs/c-runtime-library/reference/memmove-wmemmove.md @@ -1,6 +1,6 @@ --- -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"] @@ -47,9 +47,9 @@ The value of *`dest`*. 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 @@ -114,4 +114,4 @@ New string: aaaabb [`_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/mkdir-wmkdir.md b/docs/c-runtime-library/reference/mkdir-wmkdir.md index 43a9a54ba6..f01bf458e6 100644 --- a/docs/c-runtime-library/reference/mkdir-wmkdir.md +++ b/docs/c-runtime-library/reference/mkdir-wmkdir.md @@ -1,6 +1,6 @@ --- -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"] @@ -8,7 +8,6 @@ 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 ); diff --git a/docs/c-runtime-library/reference/msize-dbg.md b/docs/c-runtime-library/reference/msize-dbg.md index 41a1c38496..01ea05ea49 100644 --- a/docs/c-runtime-library/reference/msize-dbg.md +++ b/docs/c-runtime-library/reference/msize-dbg.md @@ -8,7 +8,6 @@ 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` @@ -39,15 +38,15 @@ On successful completion, **`_msize_dbg`** returns the size (in bytes) of the sp **`_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're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and the debug versions, 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_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. +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`** | \ | +| **`_msize_dbg`** | `` | For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/msize.md b/docs/c-runtime-library/reference/msize.md index 7fb3e9a872..b5d1cad10b 100644 --- a/docs/c-runtime-library/reference/msize.md +++ b/docs/c-runtime-library/reference/msize.md @@ -1,7 +1,7 @@ --- 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_type: ["DLLExport"] @@ -34,9 +34,9 @@ Pointer to the memory block. 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](../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 behavior, see [Global state in the CRT](../global-state.md). diff --git a/docs/c-runtime-library/reference/nextafter-functions.md b/docs/c-runtime-library/reference/nextafter-functions.md index da24da3c06..f4945d818e 100644 --- a/docs/c-runtime-library/reference/nextafter-functions.md +++ b/docs/c-runtime-library/reference/nextafter-functions.md @@ -56,7 +56,7 @@ 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 from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../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. diff --git a/docs/c-runtime-library/reference/not-eq.md b/docs/c-runtime-library/reference/not-eq.md index e4801590af..90877cd219 100644 --- a/docs/c-runtime-library/reference/not-eq.md +++ b/docs/c-runtime-library/reference/not-eq.md @@ -1,17 +1,16 @@ --- 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` -An alternative to the **`!=`** operator. +An alternative spelling for the **`!=`** operator. ## Syntax @@ -21,34 +20,40 @@ An alternative to the **`!=`** operator. ## 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 79b2505646..a878828337 100644 --- a/docs/c-runtime-library/reference/not.md +++ b/docs/c-runtime-library/reference/not.md @@ -1,13 +1,12 @@ --- -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` @@ -16,7 +15,6 @@ An alternative to the **`!`** operator. ## Syntax ```C - #define not ! ``` diff --git a/docs/c-runtime-library/reference/open-osfhandle.md b/docs/c-runtime-library/reference/open-osfhandle.md index cc52f6cf30..6ea534a28c 100644 --- a/docs/c-runtime-library/reference/open-osfhandle.md +++ b/docs/c-runtime-library/reference/open-osfhandle.md @@ -44,7 +44,7 @@ These manifest constants are defined in ``: |--|--| | `_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_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. diff --git a/docs/c-runtime-library/reference/open-wopen.md b/docs/c-runtime-library/reference/open-wopen.md index 487b3a3f0b..6b72d3b25f 100644 --- a/docs/c-runtime-library/reference/open-wopen.md +++ b/docs/c-runtime-library/reference/open-wopen.md @@ -79,7 +79,7 @@ The **`_open`** function opens the file specified by *`filename`* and prepares i | `_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 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_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. | diff --git a/docs/c-runtime-library/reference/or-eq.md b/docs/c-runtime-library/reference/or-eq.md index faccf4efc1..86d34f9fb7 100644 --- a/docs/c-runtime-library/reference/or-eq.md +++ b/docs/c-runtime-library/reference/or-eq.md @@ -1,13 +1,12 @@ --- -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` @@ -16,7 +15,6 @@ An alternative to the `|=` operator. ## Syntax ```C - #define or_eq |= ``` diff --git a/docs/c-runtime-library/reference/or.md b/docs/c-runtime-library/reference/or.md index 4f0035c61e..43c77e35ed 100644 --- a/docs/c-runtime-library/reference/or.md +++ b/docs/c-runtime-library/reference/or.md @@ -5,7 +5,7 @@ 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 --- diff --git a/docs/c-runtime-library/reference/pipe.md b/docs/c-runtime-library/reference/pipe.md index de49769314..084b7d4666 100644 --- a/docs/c-runtime-library/reference/pipe.md +++ b/docs/c-runtime-library/reference/pipe.md @@ -59,7 +59,7 @@ The standard output descriptor of `PROGRAM1` is attached to the pipe's write des 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`](../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 shouldn't be referenced by any thread until after the **`_pipe`** call is complete. @@ -105,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; diff --git a/docs/c-runtime-library/reference/popen-wpopen.md b/docs/c-runtime-library/reference/popen-wpopen.md index 0684bfa70c..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_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` @@ -85,7 +84,7 @@ 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](../crt-library-features.md). #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"); + } } ``` diff --git a/docs/c-runtime-library/reference/posix-write.md b/docs/c-runtime-library/reference/posix-write.md index a67ee891fb..7c80fce32a 100644 --- a/docs/c-runtime-library/reference/posix-write.md +++ b/docs/c-runtime-library/reference/posix-write.md @@ -6,7 +6,7 @@ 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 --- 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 2cac422792..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,6 +1,6 @@ --- -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"] @@ -8,11 +8,10 @@ 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` -Writes a character to a stream without locking the thread. +Writes a character to a stream without locking. ## Syntax 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 b3e11e0e26..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,6 +1,6 @@ --- -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"] @@ -8,11 +8,10 @@ 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` -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). 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 4748670c50..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` -Writes a character to `stdout` without locking the thread. +Writes a character to `stdout` without locking. ## Syntax 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 31b8fd94bb..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,21 +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_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"] +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 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 @@ -56,11 +58,13 @@ The **`_putenv_s`** function adds new environment variables or modifies the valu By 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 + +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 | +| `tchar.h` function | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | |---|---|---|---| -| `_tputenv_s` | **`_putenv_s`** | **`_putenv_s`** | **`_wputenv_s`** | +| `_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`*. diff --git a/docs/c-runtime-library/reference/qsort.md b/docs/c-runtime-library/reference/qsort.md index b465c704a9..9364fefb82 100644 --- a/docs/c-runtime-library/reference/qsort.md +++ b/docs/c-runtime-library/reference/qsort.md @@ -1,7 +1,7 @@ --- 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_type: ["DLLExport"] @@ -45,7 +45,7 @@ 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. diff --git a/docs/c-runtime-library/reference/raise.md b/docs/c-runtime-library/reference/raise.md index 2b33716eae..e3fe3e05b6 100644 --- a/docs/c-runtime-library/reference/raise.md +++ b/docs/c-runtime-library/reference/raise.md @@ -14,7 +14,7 @@ helpviewer_keywords: ["signals, sending to executing programs", "raise function" 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 diff --git a/docs/c-runtime-library/reference/read.md b/docs/c-runtime-library/reference/read.md index ad0fc6fd92..2e7096eca6 100644 --- a/docs/c-runtime-library/reference/read.md +++ b/docs/c-runtime-library/reference/read.md @@ -1,6 +1,6 @@ --- -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"] @@ -123,4 +123,4 @@ Read 19 bytes from file [`_creat`, `_wcreat`](creat-wcreat.md)\ [`fread`](fread.md)\ [`_open`, `_wopen`](open-wopen.md)\ -[`_write`](write.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 ed270641f3..7fe5026780 100644 --- a/docs/c-runtime-library/reference/realloc-dbg.md +++ b/docs/c-runtime-library/reference/realloc-dbg.md @@ -57,7 +57,7 @@ On successful completion, this function either returns a pointer to the user por **`_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're used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between standard heap functions and debug versions, 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 diff --git a/docs/c-runtime-library/reference/realloc.md b/docs/c-runtime-library/reference/realloc.md index 34e26c19e9..164743a684 100644 --- a/docs/c-runtime-library/reference/realloc.md +++ b/docs/c-runtime-library/reference/realloc.md @@ -60,7 +60,7 @@ _set_new_mode(1); 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 isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). diff --git a/docs/c-runtime-library/reference/recalloc-dbg.md b/docs/c-runtime-library/reference/recalloc-dbg.md index dc7477217e..66707f8e61 100644 --- a/docs/c-runtime-library/reference/recalloc-dbg.md +++ b/docs/c-runtime-library/reference/recalloc-dbg.md @@ -41,7 +41,7 @@ Requested size of each memory block (bytes). *`blockType`*\ Requested type of memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -For information about the allocation block types and how they're 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`. @@ -63,7 +63,7 @@ On successful completion, this function either returns a pointer to the user por **`_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 standard heap functions and debug versions, 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 diff --git a/docs/c-runtime-library/reference/recalloc.md b/docs/c-runtime-library/reference/recalloc.md index 395363ff12..09cd09dea3 100644 --- a/docs/c-runtime-library/reference/recalloc.md +++ b/docs/c-runtime-library/reference/recalloc.md @@ -1,6 +1,6 @@ --- -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"] @@ -8,7 +8,6 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_recalloc", "recalloc"] helpviewer_keywords: ["_recalloc function", "recalloc function"] -ms.assetid: 1db8305a-3f03-418c-8844-bf9149f63046 --- # `_recalloc` @@ -18,7 +17,7 @@ A combination of `realloc` and `calloc`. Reallocates an array in memory and init ```C void *_recalloc( - void *memblock + void *memblock, size_t num, size_t size ); @@ -61,7 +60,7 @@ _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 isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). diff --git a/docs/c-runtime-library/reference/remquo-remquof-remquol.md b/docs/c-runtime-library/reference/remquo-remquof-remquol.md index 9aa9613702..f6236f9679 100644 --- a/docs/c-runtime-library/reference/remquo-remquof-remquol.md +++ b/docs/c-runtime-library/reference/remquo-remquof-remquol.md @@ -8,7 +8,6 @@ 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` @@ -43,7 +42,7 @@ A pointer to an integer to store a value that has the sign and approximate magni ## Remarks -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`*. +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`**. diff --git a/docs/c-runtime-library/reference/rmtmp.md b/docs/c-runtime-library/reference/rmtmp.md index 857dc4c035..7fac6abd1a 100644 --- a/docs/c-runtime-library/reference/rmtmp.md +++ b/docs/c-runtime-library/reference/rmtmp.md @@ -1,6 +1,6 @@ --- -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"] @@ -8,7 +8,6 @@ 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` @@ -17,7 +16,6 @@ Removes temporary files. ## Syntax ```C - int _rmtmp( void ); ``` 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 dfdbaae96f..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,7 +8,6 @@ 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` @@ -17,7 +16,6 @@ Rotates bits to the left (**`_rotl`**) or right (**`_rotr`**). ## Syntax ```C - unsigned int _rotl( unsigned int value, int shift 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 e8c4e0bcf0..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 @@ -69,7 +69,7 @@ If an `_RPT` macro is called, and `_CrtSetReportMode` and `_CrtSetReportFile` ha | `_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. 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 [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. diff --git a/docs/c-runtime-library/reference/rtc-numerrors.md b/docs/c-runtime-library/reference/rtc-numerrors.md index d512c8f402..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,7 +8,6 @@ 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` @@ -17,7 +16,6 @@ Returns the total number of errors that can be detected by run-time error checks ## Syntax ```C - int _RTC_NumErrors( void ); ``` diff --git a/docs/c-runtime-library/reference/set-abort-behavior.md b/docs/c-runtime-library/reference/set-abort-behavior.md index 1abfb48f28..957edb7430 100644 --- a/docs/c-runtime-library/reference/set-abort-behavior.md +++ b/docs/c-runtime-library/reference/set-abort-behavior.md @@ -14,7 +14,7 @@ helpviewer_keywords: ["aborting programs", "_set_abort_behavior function", "set_ 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 diff --git a/docs/c-runtime-library/reference/set-se-translator.md b/docs/c-runtime-library/reference/set-se-translator.md index d695b3975d..a52026c5df 100644 --- a/docs/c-runtime-library/reference/set-se-translator.md +++ b/docs/c-runtime-library/reference/set-se-translator.md @@ -1,6 +1,6 @@ --- -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"] @@ -212,4 +212,4 @@ Caught SE_Exception, error c0000094 [`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-unexpected-crt.md b/docs/c-runtime-library/reference/set-unexpected-crt.md index c6bc98683d..8b5ee60a84 100644 --- a/docs/c-runtime-library/reference/set-unexpected-crt.md +++ b/docs/c-runtime-library/reference/set-unexpected-crt.md @@ -1,6 +1,6 @@ --- -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"] @@ -8,7 +8,6 @@ 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) @@ -62,4 +61,4 @@ For more compatibility information, see [Compatibility](../compatibility.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/setlocale-wsetlocale.md b/docs/c-runtime-library/reference/setlocale-wsetlocale.md index 59d994dc06..99991d91a3 100644 --- a/docs/c-runtime-library/reference/setlocale-wsetlocale.md +++ b/docs/c-runtime-library/reference/setlocale-wsetlocale.md @@ -1,7 +1,7 @@ --- title: "setlocale, _wsetlocale" description: "Describes the Microsoft C runtime (CRT) library functions setlocale and _wsetlocale." -ms.date: 05/05/2022 +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_type: ["DLLExport"] @@ -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 @@ -38,10 +39,19 @@ Locale specifier. ## Return value 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: -If the *`locale`* or *`category`* isn't valid, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, each function sets `errno` to `EINVAL`, and returns `NULL`. +|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 | -The call +The call: ```C setlocale( LC_ALL, "en-US" ); @@ -77,7 +87,7 @@ The *`category`* argument specifies the parts of a program's locale information | `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](../parameter-validation.md). If execution is allowed to continue, the function sets `errno` to `EINVAL` and returns `NULL`. @@ -172,7 +182,7 @@ The function [`_configthreadlocale`](configthreadlocale.md) is used to control w ## UTF-8 support -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")` 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: @@ -191,7 +201,7 @@ The following examples show how to specify the UTF-8 string: 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 isn't 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'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). @@ -248,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; @@ -288,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) { @@ -306,10 +315,10 @@ 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 diff --git a/docs/c-runtime-library/reference/setmode.md b/docs/c-runtime-library/reference/setmode.md index 6cf30c8844..009bc3bdff 100644 --- a/docs/c-runtime-library/reference/setmode.md +++ b/docs/c-runtime-library/reference/setmode.md @@ -41,7 +41,7 @@ For more information about these and other return codes, see [`errno`, `_doserrn ## 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. diff --git a/docs/c-runtime-library/reference/signal.md b/docs/c-runtime-library/reference/signal.md index 5c04a53d90..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 @@ -56,7 +56,7 @@ By default, **`signal`** terminates the calling program with exit code 3, regard > [!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. -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'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. +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'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. diff --git a/docs/c-runtime-library/reference/sin-sinf-sinl.md b/docs/c-runtime-library/reference/sin-sinf-sinl.md index 82e1d8745b..841be1e4a4 100644 --- a/docs/c-runtime-library/reference/sin-sinf-sinl.md +++ b/docs/c-runtime-library/reference/sin-sinf-sinl.md @@ -96,4 +96,4 @@ cos( 1.570796 ) = 0.000000 [`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`](../cisin.md)\ +[`_CIsin`](../cisin.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 a187f9cac4..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 functions 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](../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], @@ -68,10 +73,10 @@ int _snwprintf_s( 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`**. +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`](../truncate.md). +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-control string. @@ -84,27 +89,46 @@ The locale to use. ## 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](../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 [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../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](../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`](../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 the detection in **`_snprintf_s`**. **`_snwprintf_s`**, like **`swprintf_s`**, writes output to a string rather than to a destination of type `FILE`. +**`_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. @@ -112,17 +136,17 @@ In C++, using these functions is simplified by template overloads; the overloads ### Generic-text routine mappings -| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|`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`** | +|**`_sntprintf_s`**|**`_snprintf_s`**|**`_snprintf_s`**|**`_snwprintf_s`**| +|**`_sntprintf_s_l`**|**`_snprintf_s_l`**|**`_snprintf_s_l`**|**`_snwprintf_s_l`**| ## Requirements -| Routine | Required header | +|Routine|Required header| |---|---| -| **`_snprintf_s`**, **`_snprintf_s_l`** | `` | -| **`_snwprintf_s`**, **`_snwprintf_s_l`** | `` or `` | +|**`_snprintf_s`**, **`_snprintf_s_l`**|``| +|**`_snwprintf_s`**, **`_snwprintf_s_l`**|`` or ``| For more compatibility information, see [Compatibility](../compatibility.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 0d5234db5d..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], @@ -86,7 +94,7 @@ int _snwprintf_l( Storage location for the output. *`count`*\ -Maximum number of characters to store. +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-control string. @@ -95,37 +103,61 @@ Format-control string. Optional arguments. *`locale`*\ -The locale to use. +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). ## Return value -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`**. +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`.\ +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](../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`](../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). > > 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 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. 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 d6e46d00ef..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,6 +1,6 @@ --- -description: "Learn more about: _sopen_s, _wsopen_s" title: "_sopen_s, _wsopen_s" +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"] @@ -8,7 +8,6 @@ api_type: ["DLLExport"] topic_type: ["apiref"] 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` @@ -29,7 +28,7 @@ errno_t _wsopen_s( const wchar_t *filename, int oflag, int shflag, - int pmode, + int pmode ); ``` @@ -95,7 +94,7 @@ The integer expression *`oflag`* is formed by combining one or more manifest con | `_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 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_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. | diff --git a/docs/c-runtime-library/reference/sopen-wsopen.md b/docs/c-runtime-library/reference/sopen-wsopen.md index 9df104ac25..c3e9b3a0aa 100644 --- a/docs/c-runtime-library/reference/sopen-wsopen.md +++ b/docs/c-runtime-library/reference/sopen-wsopen.md @@ -88,7 +88,7 @@ The integer expression *`oflag`* is formed by combining one or more of the follo | `_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 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_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. | diff --git a/docs/c-runtime-library/reference/splitpath-wsplitpath.md b/docs/c-runtime-library/reference/splitpath-wsplitpath.md index 216a8c9caa..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_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 @@ -42,19 +41,19 @@ Full path. 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 don't need the directory path. +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 don't need the filename. +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 don't need the filename extension. +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 behavior, see [Global state in the CRT](../global-state.md). @@ -81,7 +80,7 @@ If the full path doesn't contain a component (for example, a filename), **`_spli 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](../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 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 8fadaa493f..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], @@ -91,13 +103,13 @@ 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`** 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](../secure-template-overloads.md). @@ -113,7 +125,7 @@ In C++, these functions have template overloads that invoke the newer, secure co | Routine | Required header | |---|---| | **`sprintf`**, **`_sprintf_l`** | `` | -| **`swprintf`**, **`_swprintf_l`** | `` or `` | +| **`swprintf`**, **`_swprintf`**, **`_swprintf_l`** | `` or `` | For more compatibility information, see [Compatibility](../compatibility.md). diff --git a/docs/c-runtime-library/reference/sqrt-sqrtf-sqrtl.md b/docs/c-runtime-library/reference/sqrt-sqrtf-sqrtl.md index a54fed2e1a..ef2221147e 100644 --- a/docs/c-runtime-library/reference/sqrt-sqrtf-sqrtl.md +++ b/docs/c-runtime-library/reference/sqrt-sqrtf-sqrtl.md @@ -97,4 +97,4 @@ The square root of 45.35 is 6.73 [`exp`, `expf`, `expl`](exp-expf.md)\ [`log`, `logf`, `log10`, `log10f`](log-logf-log10-log10f.md)\ [`pow`, `powf`, `powl`](pow-powf-powl.md)\ -[`_CIsqrt`](../cisqrt.md)\ +[`_CIsqrt`](../cisqrt.md) diff --git a/docs/c-runtime-library/reference/stat-functions.md b/docs/c-runtime-library/reference/stat-functions.md index 8d0c3eaa7b..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_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` @@ -95,6 +94,7 @@ Variations of these functions support 32-bit or 64-bit time types, and 32-bit or > [!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](../parameter-validation.md). 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 8ff8111b4e..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 @@ -6,7 +6,7 @@ api_name: ["wcscoll", "_mbscoll", "_mbscoll_l", "strcoll", "_strcoll_l", "_wcsco api_location: ["msvcrt.dll", "msvcr80.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 --- 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 6cb2d80b62..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 @@ -15,7 +15,7 @@ ms.assetid: ae37c223-800f-48a9-ae8e-38c8d20af2dd 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 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 07f652b47c..7f5a94682a 100644 --- a/docs/c-runtime-library/reference/strdup-dbg-wcsdup-dbg.md +++ b/docs/c-runtime-library/reference/strdup-dbg-wcsdup-dbg.md @@ -53,7 +53,7 @@ Each of these functions returns a pointer to the storage location for the copied 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 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](/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 @@ -77,4 +77,4 @@ All debug versions of the [C run-time libraries](../crt-library-features.md). [String manipulation](../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) +[Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md) 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 eb0c5010b0..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,14 +1,13 @@ --- 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_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` @@ -104,9 +103,9 @@ 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`](../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. 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 38efb38503..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,14 +1,13 @@ --- 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_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` @@ -51,7 +50,7 @@ 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`](../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. 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 0ffb8ffde9..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 @@ -6,7 +6,7 @@ api_name: ["_mbsicoll_l", "_stricoll_l", "_mbsicoll", "_wcsicoll_l", "_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-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 --- 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 3ca626efc4..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,6 +1,6 @@ --- -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"] @@ -184,4 +184,4 @@ You can see that `BadAppend` caused a buffer overrun. [`_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)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.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 4ca437d019..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,6 +1,6 @@ --- -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"] @@ -8,7 +8,6 @@ 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` @@ -105,8 +104,8 @@ For more compatibility information, see [Compatibility](../compatibility.md). ```C // crt_mbsnbcnt.c -#include -#include +#include +#include int main( void ) { 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 962ce66151..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 @@ -6,7 +6,7 @@ api_name: ["_strncoll", "_mbsncoll_l", "_wcsncoll", "_wcsncoll_l", "_mbsncoll", api_location: ["msvcrt.dll", "msvcr80.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 --- 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 ddf9483e51..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_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](../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 @@ -168,12 +169,16 @@ The debug library versions of these functions first fill the buffer with 0xFE. T By 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 + +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 | +| `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. They're provided just for `_tcsncpy_s_l` and aren't intended to be called directly. 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 a45259ea86..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 @@ -6,7 +6,7 @@ api_name: ["_mbsnicoll_l", "_mbsnicoll", "_wcsnicoll_l", "_strnicoll", "_strnico api_location: ["msvcrt.dll", "msvcr80.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 --- 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 61f514871a..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,22 +1,23 @@ --- 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_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](../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). +For `_tcsnset_s`, `_tcsnset_s_l`, `_tcsncset_s`, and `_tcsncset_s_l` see [Generic-text function mappings](#generic-text-function-mappings). + ## Syntax ```C @@ -92,26 +93,30 @@ These functions set, at most, the first *`count`* characters of *`str`* to *`c`* 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 behavior, see [Global state in the CRT](../global-state.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` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +| `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`** | +| `_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`** | \ | +| **`_strnset_s`** | `` | +| **`_strnset_s_l`** | `` | +| **`_wcsnset_s`** | `` or `` | +| **`_wcsnset_s_l`** | `` | +| **`_mbsnset_s`**, **`_mbsnset_s_l`** | `` | For more compatibility information, see [Compatibility](../compatibility.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 90ada77650..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,6 +1,6 @@ --- -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"] @@ -131,4 +131,4 @@ For an example of using **`strrchr`**, see [`strchr`](strchr-wcschr-mbschr-mbsch [`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/strtoimax-strtoimax-l-wcstoimax-wcstoimax-l.md b/docs/c-runtime-library/reference/strtoimax-strtoimax-l-wcstoimax-wcstoimax-l.md index c6bcf88b3f..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,14 +1,13 @@ --- -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` 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 991ab61e98..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 @@ -6,7 +6,7 @@ api_name: ["_wcstok_s_l", "_mbstok_s_l", "_mbstok_s", "strtok_s", "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_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 --- 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 891aa00f0d..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 @@ -6,7 +6,7 @@ api_name: ["_mbstok_l", "_mbstok", "wcstok", "_mbstok", "strtok", "_wcstok_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_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 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 01f3d1880b..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 @@ -6,7 +6,7 @@ api_name: ["strtol", "wcstol", "_strtol_l", "_wcstol_l", "_o__strtol_l", "_o__wc api_location: ["msvcrt.dll", "msvcr80.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"] 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] --- 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 3825ba2770..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 @@ -6,7 +6,7 @@ api_name: ["wcstold", "strtold", "_strtold_l", "_wcstold_l", "_o__strtold_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_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` 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 d2cb4475f8..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 @@ -6,7 +6,7 @@ api_name: ["strtoll", "wcstoll", "_strtoll_l", "_wcstoll_l", "_o__strtoll_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_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 --- 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 62e45135ec..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 @@ -6,7 +6,7 @@ api_name: ["_wcstoul_l", "_strtoul_l", "strtoul", "wcstoul", "_o__strtoul_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_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"] --- # `strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l` 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 bfe3fcdaec..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 @@ -6,7 +6,7 @@ api_name: ["_strtoull_l", "_wcstoull_l", "strtoull", "wcstoull", "_o__strtoull_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_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 --- 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 1375351b56..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,7 +6,7 @@ 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 --- @@ -88,10 +88,7 @@ A *`whitespace`* may consist of space and tab characters, which are ignored. *`d | Routine | Required header | |---|---| -| **`strtoumax`** | \ | -| **`wcstoumax`** | \ or \ | -| **`_strtoumax_l`** | \ | -| **`_wcstoumax_l`** | \ or \ | +| **`strtoumax`**, **`wcstoumax`**, **`_strtoumax_l`**, **`_wcstoumax_l`** | \ | For more compatibility information, see [Compatibility](../compatibility.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 d4617bb2cd..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 @@ -6,7 +6,7 @@ api_name: ["_strupr_s", "_strupr_s_l", "_mbsupr_s", "_wcsupr_s_l", "_mbsupr_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_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 --- 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 b4bb9137be..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 @@ -6,7 +6,7 @@ api_name: ["_mbsupr_l", "_mbsupr", "_strupr_l", "_wcsupr", "_wcsupr_l", "_strupr 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 --- diff --git a/docs/c-runtime-library/reference/strupr-wcsupr.md b/docs/c-runtime-library/reference/strupr-wcsupr.md index b11235455a..1b25726e49 100644 --- a/docs/c-runtime-library/reference/strupr-wcsupr.md +++ b/docs/c-runtime-library/reference/strupr-wcsupr.md @@ -6,7 +6,7 @@ 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 --- 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 4b8d2bb8c0..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 @@ -6,7 +6,7 @@ api_name: ["strxfrm", "_wcsxfrm_l", "_strxfrm_l", "wcsxfrm", "_o__strxfrm_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_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 --- diff --git a/docs/c-runtime-library/reference/swab.md b/docs/c-runtime-library/reference/swab.md index a6c0d0509d..2eb748ef51 100644 --- a/docs/c-runtime-library/reference/swab.md +++ b/docs/c-runtime-library/reference/swab.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/reference/system-wsystem.md b/docs/c-runtime-library/reference/system-wsystem.md index 23ad8b3f09..7afde9d491 100644 --- a/docs/c-runtime-library/reference/system-wsystem.md +++ b/docs/c-runtime-library/reference/system-wsystem.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/reference/tan-tanf-tanl.md b/docs/c-runtime-library/reference/tan-tanf-tanl.md index fa32e9e62c..815d0b95a9 100644 --- a/docs/c-runtime-library/reference/tan-tanf-tanl.md +++ b/docs/c-runtime-library/reference/tan-tanf-tanl.md @@ -6,8 +6,8 @@ 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_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` diff --git a/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md b/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md index 863eade0ca..de71ee3178 100644 --- a/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md +++ b/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md @@ -6,8 +6,8 @@ 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_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` diff --git a/docs/c-runtime-library/reference/tell-telli64.md b/docs/c-runtime-library/reference/tell-telli64.md index fe9aa210f2..9e7cc0ff45 100644 --- a/docs/c-runtime-library/reference/tell-telli64.md +++ b/docs/c-runtime-library/reference/tell-telli64.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/reference/tell.md b/docs/c-runtime-library/reference/tell.md index 3422228a26..3c48b55f02 100644 --- a/docs/c-runtime-library/reference/tell.md +++ b/docs/c-runtime-library/reference/tell.md @@ -6,7 +6,7 @@ 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 --- 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 e06b583cc8..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,7 +6,7 @@ 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 --- @@ -61,7 +61,7 @@ Each function returns a pointer to the name generated or `NULL` if there's a fai 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 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](/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 @@ -81,4 +81,4 @@ For more compatibility information, see [Compatibility](../compatibility.md). [`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md)\ [Stream I/O](../stream-i-o.md)\ -[Debug versions of heap allocation functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions) +[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 f7c406980f..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,7 +6,7 @@ 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 --- diff --git a/docs/c-runtime-library/reference/tempnam.md b/docs/c-runtime-library/reference/tempnam.md index 01d002181d..230f6c67c2 100644 --- a/docs/c-runtime-library/reference/tempnam.md +++ b/docs/c-runtime-library/reference/tempnam.md @@ -6,7 +6,7 @@ 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 --- diff --git a/docs/c-runtime-library/reference/terminate-crt.md b/docs/c-runtime-library/reference/terminate-crt.md index 5cea25a23b..cda2e499e5 100644 --- a/docs/c-runtime-library/reference/terminate-crt.md +++ b/docs/c-runtime-library/reference/terminate-crt.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md b/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md index b6b48deac2..eb9595efd4 100644 --- a/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md +++ b/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md @@ -6,7 +6,7 @@ api_name: ["tgamma", "tgammaf", "tgammal", "_o_tgamma", "_o_tgammaf", "_o_tgamma api_location: ["msvcrt.dll", "msvcr80.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 --- diff --git a/docs/c-runtime-library/reference/time-time32-time64.md b/docs/c-runtime-library/reference/time-time32-time64.md index 2d90eaae99..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 --- 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 48983cf8df..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 @@ -6,7 +6,7 @@ api_name: ["timespec_get", "_timespec32_get", "_timespec64_get", "_o__timespec32 api_location: ["msvcrt.dll", "msvcr80.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 --- diff --git a/docs/c-runtime-library/reference/tmpfile-s.md b/docs/c-runtime-library/reference/tmpfile-s.md index eacbfabb8f..d71b77dcea 100644 --- a/docs/c-runtime-library/reference/tmpfile-s.md +++ b/docs/c-runtime-library/reference/tmpfile-s.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/reference/tmpfile.md b/docs/c-runtime-library/reference/tmpfile.md index 0f1d2eaea0..53f2b59e95 100644 --- a/docs/c-runtime-library/reference/tmpfile.md +++ b/docs/c-runtime-library/reference/tmpfile.md @@ -6,7 +6,7 @@ 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 --- 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 2078465d5a..bb547ff8fe 100644 --- a/docs/c-runtime-library/reference/tmpnam-s-wtmpnam-s.md +++ b/docs/c-runtime-library/reference/tmpnam-s-wtmpnam-s.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/reference/toascii-toascii.md b/docs/c-runtime-library/reference/toascii-toascii.md index 89431498f4..590d1ddca7 100644 --- a/docs/c-runtime-library/reference/toascii-toascii.md +++ b/docs/c-runtime-library/reference/toascii-toascii.md @@ -6,7 +6,7 @@ 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 --- 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 928e27355d..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 @@ -6,7 +6,7 @@ api_name: ["_tolower_l", "towlower", "tolower", "_tolower", "_towlower_l", "_o__ 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 --- 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 780a9e7375..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 @@ -6,9 +6,8 @@ api_name: ["_toupper_l", "towupper", "toupper", "_towupper_l", "_toupper", "_o__ api_location: ["msvcrt.dll", "msvcr80.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` @@ -52,19 +51,17 @@ If *`c`* is a wide character for which `iswlower` is nonzero and there's a corre There's 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. - ## 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](../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. +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 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 | +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | |---|---|---|---| | `_totupper` | **`toupper`** | **`_mbctoupper`** | **`towupper`** | | `_totupper_l` | **`_toupper_l`** | **`_mbctoupper_l`** | **`_towupper_l`** | diff --git a/docs/c-runtime-library/reference/towctrans.md b/docs/c-runtime-library/reference/towctrans.md index 1b3094f66c..6cf88abded 100644 --- a/docs/c-runtime-library/reference/towctrans.md +++ b/docs/c-runtime-library/reference/towctrans.md @@ -6,7 +6,7 @@ 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 --- diff --git a/docs/c-runtime-library/reference/trunc-truncf-truncl.md b/docs/c-runtime-library/reference/trunc-truncf-truncl.md index df5fa620e2..19c7bc0414 100644 --- a/docs/c-runtime-library/reference/trunc-truncf-truncl.md +++ b/docs/c-runtime-library/reference/trunc-truncf-truncl.md @@ -6,7 +6,7 @@ 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 --- diff --git a/docs/c-runtime-library/reference/tzset.md b/docs/c-runtime-library/reference/tzset.md index 6779735a34..23fcafc53d 100644 --- a/docs/c-runtime-library/reference/tzset.md +++ b/docs/c-runtime-library/reference/tzset.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/reference/uncaught-exception.md b/docs/c-runtime-library/reference/uncaught-exception.md index 82ee1ebcc4..52c7a6c349 100644 --- a/docs/c-runtime-library/reference/uncaught-exception.md +++ b/docs/c-runtime-library/reference/uncaught-exception.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/reference/unexpected-crt.md b/docs/c-runtime-library/reference/unexpected-crt.md index 68940b40b5..a1fabd706f 100644 --- a/docs/c-runtime-library/reference/unexpected-crt.md +++ b/docs/c-runtime-library/reference/unexpected-crt.md @@ -6,7 +6,7 @@ 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_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["unexpected"] +f1_keywords: ["EH/unexpected"] helpviewer_keywords: ["unexpected function"] ms.assetid: 2f873763-15ad-4556-a924-dcf28f2b52b4 --- 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 035231ecb0..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_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` -Pushes a character back onto the stream. +Pushes a character back onto the stream without locking. ## Syntax diff --git a/docs/c-runtime-library/reference/ungetc-ungetwc.md b/docs/c-runtime-library/reference/ungetc-ungetwc.md index c0ccaa5cc3..fe97a8b26f 100644 --- a/docs/c-runtime-library/reference/ungetc-ungetwc.md +++ b/docs/c-runtime-library/reference/ungetc-ungetwc.md @@ -6,7 +6,7 @@ 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_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 --- 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 8daa37df83..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,14 +1,13 @@ --- -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_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` diff --git a/docs/c-runtime-library/reference/ungetch.md b/docs/c-runtime-library/reference/ungetch.md index eff10668ec..668a233b35 100644 --- a/docs/c-runtime-library/reference/ungetch.md +++ b/docs/c-runtime-library/reference/ungetch.md @@ -6,7 +6,7 @@ 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 --- diff --git a/docs/c-runtime-library/reference/unlink-wunlink.md b/docs/c-runtime-library/reference/unlink-wunlink.md index 93226faab7..2a0dba15a7 100644 --- a/docs/c-runtime-library/reference/unlink-wunlink.md +++ b/docs/c-runtime-library/reference/unlink-wunlink.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/reference/unlink.md b/docs/c-runtime-library/reference/unlink.md index 94c5dbba50..58c351ba3a 100644 --- a/docs/c-runtime-library/reference/unlink.md +++ b/docs/c-runtime-library/reference/unlink.md @@ -6,7 +6,7 @@ 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 --- diff --git a/docs/c-runtime-library/reference/unlock-file.md b/docs/c-runtime-library/reference/unlock-file.md index de108f995f..af13c9ba9f 100644 --- a/docs/c-runtime-library/reference/unlock-file.md +++ b/docs/c-runtime-library/reference/unlock-file.md @@ -6,7 +6,7 @@ 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_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 --- 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 422b257bc2..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 @@ -6,7 +6,7 @@ api_name: ["_utime64", "_utime", "_wutime", "_wutime64", "_wutime32", "_utime32" api_location: ["msvcrt.dll", "msvcr80.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 --- @@ -77,7 +77,7 @@ The **`_utimbuf`** structure stores file access and modification times used by * | **`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 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. +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. 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 95bc6590d0..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 --- 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 9820f20c84..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,7 +6,7 @@ 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` 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 4cb308d94f..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,7 +6,7 @@ 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` @@ -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 ); 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 7d9c4d1807..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,7 +6,7 @@ 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` 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 c7236e7ba8..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,7 +6,7 @@ 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` 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 02016e4921..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,7 +6,7 @@ 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` 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 74b46fb124..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,7 +6,7 @@ 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` 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 86e6bca7b3..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,7 +6,7 @@ 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` diff --git a/docs/c-runtime-library/reference/vfscanf-vfwscanf.md b/docs/c-runtime-library/reference/vfscanf-vfwscanf.md index 00213ccfee..152140dd56 100644 --- a/docs/c-runtime-library/reference/vfscanf-vfwscanf.md +++ b/docs/c-runtime-library/reference/vfscanf-vfwscanf.md @@ -6,7 +6,7 @@ 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` 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 10c9938909..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,7 +6,7 @@ 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` 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 8d0723df48..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,7 +6,7 @@ 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` 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 06c7ce852b..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,7 +6,7 @@ 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` 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 ab7868f6b8..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,7 +6,7 @@ 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` diff --git a/docs/c-runtime-library/reference/vscanf-vwscanf.md b/docs/c-runtime-library/reference/vscanf-vwscanf.md index 08abfd22f6..043913e4b2 100644 --- a/docs/c-runtime-library/reference/vscanf-vwscanf.md +++ b/docs/c-runtime-library/reference/vscanf-vwscanf.md @@ -6,7 +6,7 @@ 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` 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 ea69b12acc..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` @@ -59,6 +59,9 @@ These functions differ from **`_vscprintf`** and **`_vscwprintf`** only in that 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. +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] @@ -89,4 +92,4 @@ See the example for [`vsprintf`](vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswpr [`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 e02f6cdb18..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,7 +6,7 @@ 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` @@ -59,6 +59,9 @@ If *`format`* is a null pointer, the invalid parameter handler is invoked, as de ## Remarks +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] 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 653f4225c7..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,12 +1,12 @@ --- 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: 09/29/2022 +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` @@ -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], @@ -75,10 +81,10 @@ int _vsnwprintf_s( Storage location for output. *`sizeOfBuffer`*\ -The size of the *`buffer`* for output, as the character count. +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`](../truncate.md). +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 specification. @@ -87,51 +93,61 @@ Format specification. Pointer to list of arguments. *`locale`*\ -The locale to use. +The locale to use when formatting the output. For more information, see [Format specifications](../format-specification-syntax-printf-and-wprintf-functions.md). ## Return value -**`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. - -* If *`count`* is less than *`sizeOfBuffer`* and the number of characters of data is less than or equal to *`count`*, or *`count`* is [`_TRUNCATE`](../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. - -* 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`](../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](../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 value | `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`](../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). > 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). @@ -196,4 +212,4 @@ nSize: -1, buff: Hi there! [`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)\ +[`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 b0fc829b06..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], @@ -93,7 +102,7 @@ int _vsnwprintf_l( Storage location for output. *`count`*\ -Maximum number of characters to write. +Maximum number of characters to write. For the functions that take `wchar_t`, it's the number of wide characters to write. *`format`*\ Format specification. @@ -108,19 +117,15 @@ For more information, see [Format specification syntax](../format-specification- ## 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. - -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. +The number of characters written, not including the terminating `NULL`, or a negative value if an output error occurs. -- If *`count`* is zero and *`buffer`* is `NULL`, the value returned is the number of characters the functions would write. The value doesn't take into account a 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. -- 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](../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 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`*). +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). @@ -129,14 +134,38 @@ Each of these functions takes a pointer to an argument list, then formats the da > [!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](../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 | `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | 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 7f67d33cd2..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,7 +6,7 @@ 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` @@ -66,7 +66,9 @@ The locale to use. ## 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 @@ -76,7 +78,7 @@ These functions differ from the `vsprintf_s` and `vswprintf_s` only in that they 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](../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). 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 645a187387..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,18 +1,20 @@ --- 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](../security-features-in-the-crt.md). +For `_vstprintf_s` and `_vstprintf_s_l`, see [Generic-text function mappings](#generic-text-function-mappings). + ## Syntax ```C @@ -94,12 +96,14 @@ In C++, using these functions is simplified by template overloads. The overloads > [!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` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +| `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`** | +| `_vstprintf_s` | `vsprintf_s` | `vsprintf_s` | `vswprintf_s` | +| `_vstprintf_s_l` | `_vsprintf_s_l` | `_vsprintf_s_l` | `_vswprintf_s_l` | ## Requirements 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 acaff8c14f..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,7 +6,7 @@ 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` @@ -95,6 +95,10 @@ The locale to use. **`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`. +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 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 e95d0c4ded..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,7 +6,7 @@ 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` diff --git a/docs/c-runtime-library/reference/vsscanf-vswscanf.md b/docs/c-runtime-library/reference/vsscanf-vswscanf.md index 1619260259..456e5cf8ad 100644 --- a/docs/c-runtime-library/reference/vsscanf-vswscanf.md +++ b/docs/c-runtime-library/reference/vsscanf-vswscanf.md @@ -6,7 +6,7 @@ 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 --- diff --git a/docs/c-runtime-library/reference/wcrtomb-s.md b/docs/c-runtime-library/reference/wcrtomb-s.md index 2b0e08a740..3f0b1ca8b4 100644 --- a/docs/c-runtime-library/reference/wcrtomb-s.md +++ b/docs/c-runtime-library/reference/wcrtomb-s.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/reference/wcrtomb.md b/docs/c-runtime-library/reference/wcrtomb.md index 6c9c7dc649..a88c83cdbe 100644 --- a/docs/c-runtime-library/reference/wcrtomb.md +++ b/docs/c-runtime-library/reference/wcrtomb.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/reference/wcsicoll.md b/docs/c-runtime-library/reference/wcsicoll.md index 7a4e304b18..5e73d3af12 100644 --- a/docs/c-runtime-library/reference/wcsicoll.md +++ b/docs/c-runtime-library/reference/wcsicoll.md @@ -6,7 +6,7 @@ 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 --- diff --git a/docs/c-runtime-library/reference/wcsrtombs-s.md b/docs/c-runtime-library/reference/wcsrtombs-s.md index 3ddf2f5a79..a56efa3cd5 100644 --- a/docs/c-runtime-library/reference/wcsrtombs-s.md +++ b/docs/c-runtime-library/reference/wcsrtombs-s.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/reference/wcsrtombs.md b/docs/c-runtime-library/reference/wcsrtombs.md index e0bce3824a..9df3eb44ee 100644 --- a/docs/c-runtime-library/reference/wcsrtombs.md +++ b/docs/c-runtime-library/reference/wcsrtombs.md @@ -6,7 +6,7 @@ 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_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 --- 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 2053407d85..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 @@ -6,7 +6,7 @@ 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_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` diff --git a/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md b/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md index 1b7b95d0f4..cd259d2102 100644 --- a/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md +++ b/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md @@ -6,7 +6,7 @@ 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_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"] --- # `wcstombs`, `_wcstombs_l` @@ -64,6 +64,8 @@ If **`wcstombs`** successfully converts the multibyte string, it returns the num 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. +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 **`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. If the *`mbstr`* argument is `NULL`, **`wcstombs`** returns the required size in bytes of the destination string. diff --git a/docs/c-runtime-library/reference/wctob.md b/docs/c-runtime-library/reference/wctob.md index 14158180c1..70b552de85 100644 --- a/docs/c-runtime-library/reference/wctob.md +++ b/docs/c-runtime-library/reference/wctob.md @@ -6,7 +6,7 @@ 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_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 --- 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 3f81370a72..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 @@ -6,7 +6,7 @@ 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_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 --- @@ -44,7 +44,7 @@ The address of a multibyte character. Size of the buffer *`mbchar`*. *`wchar`*\ -A wide character. +The wide character to convert. *`locale`*\ The locale to use. @@ -60,9 +60,11 @@ Error Conditions | `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`. +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. diff --git a/docs/c-runtime-library/reference/wctomb-wctomb-l.md b/docs/c-runtime-library/reference/wctomb-wctomb-l.md index 25e7712a3a..003b081d84 100644 --- a/docs/c-runtime-library/reference/wctomb-wctomb-l.md +++ b/docs/c-runtime-library/reference/wctomb-wctomb-l.md @@ -6,7 +6,7 @@ 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_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 --- diff --git a/docs/c-runtime-library/reference/wctrans.md b/docs/c-runtime-library/reference/wctrans.md index d48a6e8f04..7bcac2489a 100644 --- a/docs/c-runtime-library/reference/wctrans.md +++ b/docs/c-runtime-library/reference/wctrans.md @@ -6,7 +6,7 @@ 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 --- diff --git a/docs/c-runtime-library/reference/wctype.md b/docs/c-runtime-library/reference/wctype.md index 220f93f169..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` diff --git a/docs/c-runtime-library/reference/write.md b/docs/c-runtime-library/reference/write.md index 41956272df..f21ee87c4d 100644 --- a/docs/c-runtime-library/reference/write.md +++ b/docs/c-runtime-library/reference/write.md @@ -6,7 +6,7 @@ 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_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_write"] +f1_keywords: ["CORECRT_IO/_write", "_write"] helpviewer_keywords: ["_write function", "write function", "files [C++], writing to"] --- # `_write` diff --git a/docs/c-runtime-library/reference/xor-eq.md b/docs/c-runtime-library/reference/xor-eq.md index 5c8ee16037..4a9898a2c2 100644 --- a/docs/c-runtime-library/reference/xor-eq.md +++ b/docs/c-runtime-library/reference/xor-eq.md @@ -5,7 +5,7 @@ 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 --- diff --git a/docs/c-runtime-library/reference/xor.md b/docs/c-runtime-library/reference/xor.md index 44770cb21e..1bc78efb8d 100644 --- a/docs/c-runtime-library/reference/xor.md +++ b/docs/c-runtime-library/reference/xor.md @@ -5,7 +5,7 @@ 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 --- @@ -39,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 762f4bfd37..6b3d311152 100644 --- a/docs/c-runtime-library/reference/y0-y1-yn.md +++ b/docs/c-runtime-library/reference/y0-y1-yn.md @@ -6,7 +6,7 @@ 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 --- diff --git a/docs/c-runtime-library/routine-mappings.md b/docs/c-runtime-library/routine-mappings.md index 64d52861ae..087515c0cd 100644 --- a/docs/c-runtime-library/routine-mappings.md +++ b/docs/c-runtime-library/routine-mappings.md @@ -1,19 +1,21 @@ --- -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'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. +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 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). -### Generic-text routine mappings +### Function mappings | Generic-text routine name | `SBCS` (`_UNICODE` and `MBCS` not defined) | `_MBCS` defined | `_UNICODE` defined | |---|---|---|---| @@ -27,6 +29,7 @@ For related information, see [Generic-text mappings in tchar.h](../text/generic- | `_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` | diff --git a/docs/c-runtime-library/rtdynamiccast.md b/docs/c-runtime-library/rtdynamiccast.md index c50aa99300..791143e7c0 100644 --- a/docs/c-runtime-library/rtdynamiccast.md +++ b/docs/c-runtime-library/rtdynamiccast.md @@ -6,9 +6,8 @@ api_name: ["__RTDynamicCast"] 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` @@ -17,13 +16,13 @@ Runtime implementation of the [`dynamic_cast`](../cpp/dynamic-cast-operator.md) ## Syntax ```cpp -PVOID __RTDynamicCast ( +PVOID __RTDynamicCast( PVOID inptr, LONG VfDelta, PVOID SrcType, PVOID TargetType, BOOL isReference - ) throw(...) +) throw(...) ``` #### Parameters @@ -45,7 +44,7 @@ Intended result of cast. ## Return value -Pointer to the appropriate subobject, if successful; otherwise, `NULL`. +Pointer to the appropriate subobject if successful; otherwise, `NULL`. ## Exceptions @@ -59,4 +58,4 @@ Converts `inptr` to an object of type `TargetType`. The type of `inptr` must be | Routine | Required header | |---|---| -| **`__RTDynamicCast`** | `` | +| **`__RTDynamicCast`** | `` | 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 6e97523932..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,7 +3,7 @@ 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 --- 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 1953ede658..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,9 +3,8 @@ 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 @@ -19,7 +18,7 @@ For example, the `strcpy` function can't tell if the string it copies is too lar ## 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 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`: @@ -54,13 +53,15 @@ Some of the security features include: 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 non-terminated strings have secure versions, which ensure that strings are properly null-terminated. + Some functions that left potentially nonterminated strings have secure versions, which ensure that strings are properly null-terminated. - **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. + 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. - **Filesystem security** diff --git a/docs/c-runtime-library/set-app-type.md b/docs/c-runtime-library/set-app-type.md index 7b644d6bc7..6b7666c279 100644 --- a/docs/c-runtime-library/set-app-type.md +++ b/docs/c-runtime-library/set-app-type.md @@ -6,7 +6,7 @@ api_name: ["_set_app_type", "_o__set_app_type"] 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` diff --git a/docs/c-runtime-library/setvbuf-constants.md b/docs/c-runtime-library/setvbuf-constants.md index a9a6965f71..06386d05fb 100644 --- a/docs/c-runtime-library/setvbuf-constants.md +++ b/docs/c-runtime-library/setvbuf-constants.md @@ -2,7 +2,7 @@ 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 --- diff --git a/docs/c-runtime-library/sharing-constants.md b/docs/c-runtime-library/sharing-constants.md index 887ae56c88..11c84f2d81 100644 --- a/docs/c-runtime-library/sharing-constants.md +++ b/docs/c-runtime-library/sharing-constants.md @@ -2,8 +2,8 @@ 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 diff --git a/docs/c-runtime-library/signal-action-constants.md b/docs/c-runtime-library/signal-action-constants.md index 13bbfc980c..17d063de1c 100644 --- a/docs/c-runtime-library/signal-action-constants.md +++ b/docs/c-runtime-library/signal-action-constants.md @@ -2,7 +2,7 @@ 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 --- @@ -24,6 +24,7 @@ The `func` argument must be either a function address or one of the manifest con |---|---| | `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. | diff --git a/docs/c-runtime-library/signal-constants.md b/docs/c-runtime-library/signal-constants.md index 0618aab2a5..24d35116ca 100644 --- a/docs/c-runtime-library/signal-constants.md +++ b/docs/c-runtime-library/signal-constants.md @@ -2,7 +2,7 @@ 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 --- @@ -21,7 +21,7 @@ The `sig` argument must be one of the manifest constants listed below (defined i | 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. | +| `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. | diff --git a/docs/c-runtime-library/spawn-constants.md b/docs/c-runtime-library/spawn-constants.md index b31b2decbf..0be2e3c4d4 100644 --- a/docs/c-runtime-library/spawn-constants.md +++ b/docs/c-runtime-library/spawn-constants.md @@ -2,7 +2,7 @@ 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 --- diff --git a/docs/c-runtime-library/spawn-wspawn-functions.md b/docs/c-runtime-library/spawn-wspawn-functions.md index e05d4f3657..97667c5c00 100644 --- a/docs/c-runtime-library/spawn-wspawn-functions.md +++ b/docs/c-runtime-library/spawn-wspawn-functions.md @@ -2,9 +2,6 @@ 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"] --- @@ -12,20 +9,14 @@ helpviewer_keywords: ["_tspawnve function", "_spawn functions", "_tspawnlpe func Each of the `_spawn` functions creates and executes a new process: -:::row::: - :::column span=""::: - [`_spawnl`, `_wspawnl`](./reference/spawnl-wspawnl.md)\ - [`_spawnle`, `_wspawnle`](./reference/spawnle-wspawnle.md)\ - [`_spawnlp`, `_wspawnlp`](./reference/spawnlp-wspawnlp.md)\ - [`_spawnlpe`, `_wspawnlpe`](./reference/spawnlpe-wspawnlpe.md) - :::column-end::: - :::column span=""::: - [`_spawnv`, `_wspawnv`](./reference/spawnv-wspawnv.md)\ - [`_spawnve`, `_wspawnve`](./reference/spawnve-wspawnve.md)\ - [`_spawnvp`, `_wspawnvp`](./reference/spawnvp-wspawnvp.md)\ - [`_spawnvpe`, `_wspawnvpe`](./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. diff --git a/docs/c-runtime-library/standard-types.md b/docs/c-runtime-library/standard-types.md index 31a35b082c..f5e544a7d2 100644 --- a/docs/c-runtime-library/standard-types.md +++ b/docs/c-runtime-library/standard-types.md @@ -1,9 +1,9 @@ --- 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 @@ -43,7 +43,7 @@ The Microsoft run-time library defines the following standard types and typedefs | `_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` | +| `_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` | 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 8adc48ed74..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,7 +2,7 @@ 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 --- diff --git a/docs/c-runtime-library/stdin-stdout-stderr.md b/docs/c-runtime-library/stdin-stdout-stderr.md index 583eb8c47d..b88b099b36 100644 --- a/docs/c-runtime-library/stdin-stdout-stderr.md +++ b/docs/c-runtime-library/stdin-stdout-stderr.md @@ -1,20 +1,18 @@ --- -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 ```C -FILE *stdin; -FILE *stdout; -FILE *stderr; -#include +#define stdin /* implementation defined */ +#define stdout /* implementation defined */ +#define stderr /* implementation defined */ ``` ## Remarks diff --git a/docs/c-runtime-library/strcoll-functions.md b/docs/c-runtime-library/strcoll-functions.md index 4bd33814e5..9677b6a42e 100644 --- a/docs/c-runtime-library/strcoll-functions.md +++ b/docs/c-runtime-library/strcoll-functions.md @@ -2,10 +2,6 @@ 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 --- diff --git a/docs/c-runtime-library/stream-i-o.md b/docs/c-runtime-library/stream-i-o.md index 180ecf2b1f..e91fcfdda2 100644 --- a/docs/c-runtime-library/stream-i-o.md +++ b/docs/c-runtime-library/stream-i-o.md @@ -1,9 +1,8 @@ --- -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 @@ -13,61 +12,61 @@ These functions process data in different sizes and formats, from single charact | 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 | +| [`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. @@ -76,16 +75,15 @@ Files opened using the stream routines are buffered by default. The **`stdout`** 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 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. +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`**). 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](./input-and-output.md)\ -[Universal C runtime routines by category](./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/string-to-numeric-value-functions.md b/docs/c-runtime-library/string-to-numeric-value-functions.md index 4696bac91c..2bc2e86709 100644 --- a/docs/c-runtime-library/string-to-numeric-value-functions.md +++ b/docs/c-runtime-library/string-to-numeric-value-functions.md @@ -2,10 +2,6 @@ description: "Learn more about: String to numeric value functions" title: "String to numeric value functions" ms.date: 05/18/2022 -api_location: ["msvcr80.dll", "msvcr110.dll", "msvcr120.dll", "msvcr100.dll", "msvcr110_clr0400.dll", "msvcr90.dll"] -api_type: ["DLLExport"] -topic_type: ["apiref"] -f1_keywords: ["_tcstoi64"] helpviewer_keywords: ["parsing, numeric strings", "string conversion, to numeric values"] ms.assetid: 11cbd9ce-033b-4914-bf66-029070e7e385 --- 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 7a3cde2713..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 @@ -11,7 +11,7 @@ File I/O operations take place in one of two translation modes, *text* or *binar - Retain the current default setting and specify the alternative mode only when you open selected files. -- 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 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`](./fmode.md) in your program. The function `_set_fmode` sets the value of this variable, but it can also be set directly. diff --git a/docs/c-runtime-library/time-management.md b/docs/c-runtime-library/time-management.md index 784c4b009a..619798b3cc 100644 --- a/docs/c-runtime-library/time-management.md +++ b/docs/c-runtime-library/time-management.md @@ -1,42 +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"] --- # 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`** 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). +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. | +| [`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. > [!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](./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](./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 53fda9f1b3..7e323d2ed0 100644 --- a/docs/c-runtime-library/tmp-max-l-tmpnam.md +++ b/docs/c-runtime-library/tmp-max-l-tmpnam.md @@ -2,7 +2,7 @@ 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 --- @@ -16,7 +16,7 @@ ms.assetid: ab19fd0c-b5b7-49f7-b23d-da9dfbcf0c1f ## 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 diff --git a/docs/c-runtime-library/to-functions.md b/docs/c-runtime-library/to-functions.md index 6aaf88b769..3cd86e5a53 100644 --- a/docs/c-runtime-library/to-functions.md +++ b/docs/c-runtime-library/to-functions.md @@ -1,13 +1,8 @@ --- 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 @@ -31,28 +26,24 @@ The **`to`** functions and macro conversions are as follows. | `_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 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. +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` 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'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](./data-conversion.md)\ -[Locale](./locale.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 a9059f68cc..b50e64e560 100644 --- a/docs/c-runtime-library/translation-mode-constants.md +++ b/docs/c-runtime-library/translation-mode-constants.md @@ -2,8 +2,8 @@ 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 @@ -16,13 +16,16 @@ ms.assetid: a5993bf4-7e7a-47f9-83c3-e46332b85579 ## 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. 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_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. | diff --git a/docs/c-runtime-library/truncate.md b/docs/c-runtime-library/truncate.md index 72c947882c..cb8dffc0d7 100644 --- a/docs/c-runtime-library/truncate.md +++ b/docs/c-runtime-library/truncate.md @@ -2,7 +2,7 @@ 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"] --- # `_TRUNCATE` 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 a45fbb30f3..9fbde6648e 100644 --- a/docs/c-runtime-library/unicode-the-wide-character-set.md +++ b/docs/c-runtime-library/unicode-the-wide-character-set.md @@ -8,7 +8,7 @@ ms.assetid: b6a05a21-59a5-4d30-8c85-2dbe185f7a74 --- # 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. diff --git a/docs/c-runtime-library/vprintf-functions.md b/docs/c-runtime-library/vprintf-functions.md index dc0fa7b150..6119ea7428 100644 --- a/docs/c-runtime-library/vprintf-functions.md +++ b/docs/c-runtime-library/vprintf-functions.md @@ -1,13 +1,8 @@ --- -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 @@ -21,7 +16,7 @@ Each of the `vprintf` functions takes a pointer to an argument list, then format [`_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) +[`_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) diff --git a/docs/c-runtime-library/wait-child-wait-grandchild.md b/docs/c-runtime-library/wait-child-wait-grandchild.md index 4ed46ab60f..26a92d87ec 100644 --- a/docs/c-runtime-library/wait-child-wait-grandchild.md +++ b/docs/c-runtime-library/wait-child-wait-grandchild.md @@ -2,7 +2,7 @@ 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 --- diff --git a/docs/c-runtime-library/wchar-max.md b/docs/c-runtime-library/wchar-max.md index b38df5c1f5..2cc4f93793 100644 --- a/docs/c-runtime-library/wchar-max.md +++ b/docs/c-runtime-library/wchar-max.md @@ -2,7 +2,7 @@ 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 --- diff --git a/docs/c-runtime-library/wchar-min.md b/docs/c-runtime-library/wchar-min.md index b003e74503..5aaeae92ae 100644 --- a/docs/c-runtime-library/wchar-min.md +++ b/docs/c-runtime-library/wchar-min.md @@ -2,7 +2,7 @@ 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 --- 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 ddf60a045a..a362074bad 100644 --- a/docs/code-quality/annotating-locking-behavior.md +++ b/docs/code-quality/annotating-locking-behavior.md @@ -33,9 +33,9 @@ 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're non-deterministic. 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. +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. @@ -64,10 +64,10 @@ 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 isn't 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're 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 isn't currently held.| @@ -97,17 +97,17 @@ 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_(lock)`|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_(lock)`|Tells the analyzer to assume that a smart lock has been released. This annotation expects a reference lock type as its parameter.| +|`_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.| diff --git a/docs/code-quality/annotating-structs-and-classes.md b/docs/code-quality/annotating-structs-and-classes.md index 32669912be..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: diff --git a/docs/code-quality/best-practices-and-examples-sal.md b/docs/code-quality/best-practices-and-examples-sal.md index ad53857311..320b8100d3 100644 --- a/docs/code-quality/best-practices-and-examples-sal.md +++ b/docs/code-quality/best-practices-and-examples-sal.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Best practices and examples (SAL)" title: Best practices and examples (SAL) -ms.date: 01/27/2022 +ms.date: 03/30/2023 ms.topic: "conceptual" --- # Best practices and examples (SAL) @@ -10,7 +10,7 @@ Here are some ways to get the most out of the Source Code Annotation Language (S ## `_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's 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 @@ -25,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; @@ -36,7 +39,7 @@ void Func2(_Inout_ PCHAR p1) ## `_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 is `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_`). +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 @@ -56,7 +59,7 @@ void Func2(_Out_ int *p1) ## `_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_` @@ -71,7 +74,7 @@ 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 isn't strictly wrong and it's helpful to express the allocated size. However, it doesn't 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. @@ -204,7 +207,7 @@ 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 doesn't 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 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/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 bbd4c04054..96db147d01 100644 --- a/docs/code-quality/c26135.md +++ b/docs/code-quality/c26135.md @@ -25,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/c26401.md b/docs/code-quality/c26401.md index ef45225be5..023338c378 100644 --- a/docs/code-quality/c26401.md +++ b/docs/code-quality/c26401.md @@ -63,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/c26409.md b/docs/code-quality/c26409.md index 8939a08776..a0dc4a4f3d 100644 --- a/docs/code-quality/c26409.md +++ b/docs/code-quality/c26409.md @@ -1,10 +1,9 @@ --- -description: "Learn more about CppCoreCheck rule C26409: avoid explicit new and delete." title: Warning C26409 +description: "Learn more about CppCoreCheck rule C26409: avoid explicit new and delete." ms.date: 12/14/2020 f1_keywords: ["C26409", "NO_NEW_DELETE"] helpviewer_keywords: ["C26409"] -ms.assetid: a3b3a229-d566-4be3-bd28-2876ccc8dc37 --- # Warning C26409 @@ -13,7 +12,7 @@ ms.assetid: a3b3a229-d566-4be3-bd28-2876ccc8dc37 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). @@ -49,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/c26414.md b/docs/code-quality/c26414.md index 471b69d1d9..d33427adcb 100644 --- a/docs/code-quality/c26414.md +++ b/docs/code-quality/c26414.md @@ -4,14 +4,13 @@ description: "Reference for Visual Studio C++ Core Guidelines code analysis warn ms.date: 01/29/2020 f1_keywords: ["C26414", "RESET_LOCAL_SMART_PTR"] helpviewer_keywords: ["C26414"] -ms.assetid: dd875d0c-6752-4491-a533-3e8831795fbc --- # 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. diff --git a/docs/code-quality/c26430.md b/docs/code-quality/c26430.md index ca0a31cf88..230352b2e9 100644 --- a/docs/code-quality/c26430.md +++ b/docs/code-quality/c26430.md @@ -27,8 +27,6 @@ A variable is marked as checked for null when it's used in the following context - in non-bitwise logical operations; - in comparison operations where one operand is a constant expression that evaluates to zero. -The rule doesn't have full data flow 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). - Implicit null checks are assumed when a pointer value is assigned from: - an allocation performed with throwing `operator new`; @@ -67,3 +65,36 @@ void merge_states(gsl::not_null left, gsl::not_null `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. diff --git a/docs/code-quality/c26434.md b/docs/code-quality/c26434.md index 7db222af1a..0bdfe9d173 100644 --- a/docs/code-quality/c26434.md +++ b/docs/code-quality/c26434.md @@ -4,7 +4,6 @@ description: "Microsoft C++ Code Analysis warning C26434 for the C++ Core Guidel ms.date: 08/21/2020 f1_keywords: ["C26434", "DONT_HIDE_METHODS"] helpviewer_keywords: ["C26434"] -ms.assetid: 7f66477f-da66-444a-a6e3-44513d7d7e31 --- # Warning C26434 @@ -44,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 f66dacda9a..ab4ec78c93 100644 --- a/docs/code-quality/c26435.md +++ b/docs/code-quality/c26435.md @@ -7,7 +7,7 @@ helpviewer_keywords: ["C26435"] --- # Warning C26435 -> Function '*symbol*' should specify exactly one of 'virtual', 'override', or 'final' (c.128) +> The virtual function '*symbol*' should specify exactly one of 'virtual', 'override', or 'final' (c.128) ## C++ Core Guidelines @@ -41,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/c26437.md b/docs/code-quality/c26437.md index f617e904ca..2f96db0776 100644 --- a/docs/code-quality/c26437.md +++ b/docs/code-quality/c26437.md @@ -1,19 +1,18 @@ --- -description: "Learn more about: Warning C26437 DONT_SLICE" title: Warning C26437 -ms.date: 10/07/2019 +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 --- # Warning C26437 > 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 the compiler 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 unmaintainable, by forcing extra requirements on related data types. It's 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 @@ -23,10 +22,9 @@ The rule also flags cases where an assignment doesn't involve real data slicing ## Example -Slicing points to outdated interface: +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; }; @@ -45,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/c26439.md b/docs/code-quality/c26439.md index 8bfaa4bb5a..85e7499a1e 100644 --- a/docs/code-quality/c26439.md +++ b/docs/code-quality/c26439.md @@ -1,41 +1,40 @@ --- title: Warning C26439 -ms.date: 11/15/2017 +description: CppCoreCheck rule C26439 that enforces C++ Core Guidelines F.6 +ms.date: 05/17/2023 f1_keywords: ["C26439", "SPECIAL_NOEXCEPT"] helpviewer_keywords: ["C26439"] -ms.assetid: 9df2a1b0-ea94-4884-9d28-c1522ec33a1b -description: CppCoreCheck rule C26439 that enforces C++ Core Guidelines F.6 --- # Warning C26439 > This kind of 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 +[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) + +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. + +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 aren't explicitly marked as `noexcept`, which means that they may throw exceptions and can't convey assumptions about their reliability. +Code analysis name: `SPECIAL_NOEXCEPT` ## Remarks - 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)` aren't equivalent to `noexcept`. +- Nonstandard and outdated specifiers like `throw()` or `declspec(nothrow)` aren't 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 check may change in future releases. - ## Example -All functions except the destructor will warn because they're 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) @@ -46,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*/} @@ -61,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/c26441.md b/docs/code-quality/c26441.md index 0230d446bb..c2f5dc91b8 100644 --- a/docs/code-quality/c26441.md +++ b/docs/code-quality/c26441.md @@ -1,60 +1,68 @@ --- -description: "Learn more about: Warning C26441 NO_UNNAMED_GUARDS" title: Warning C26441 -ms.date: 11/15/2017 +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 --- # Warning C26441 > 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 that help to control concurrent access to resources. Objects of such types lock exclusive access during their lifetime. Lifetime management implies that every lock object must be named. That is, it must have a clearly defined lifetime that spans through the period in which access operations are executed. So, failing to assign a lock object to a variable is a mistake that effectively disables the 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`. +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. -- Only simple calls to constructors are analyzed. More complex initializer expressions may lead to inaccurate results, but it's an unusual scenario. +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. -- Locks passed as arguments to function calls or returned as results of function calls are ignored. +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: -- Locks created as temporaries but assigned to named references to extend their lifetime are ignored. +```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/c26444.md b/docs/code-quality/c26444.md index bad8c2812a..cc020442fe 100644 --- a/docs/code-quality/c26444.md +++ b/docs/code-quality/c26444.md @@ -1,53 +1,49 @@ --- -description: "Learn more about: Warning C26444 NO_UNNAMED_RAII_OBJECTS" title: Warning C26444 -ms.date: 01/18/2017 +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"] --- # 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 isn't 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. +- 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. -- 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's customary to ignore iterators returned from calls like [`std::vector::insert`](../standard-library/vector-class.md#insert). While such warnings aren't actionable in most cases, they're legitimate in pointing to the place where some non-obvious work is done in temporary objects. Code analysis name: `NO_UNNAMED_RAII_OBJECTS` -## Example: Ignored call result +## 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/c26449.md b/docs/code-quality/c26449.md index 4dce008f58..85de9ef0c3 100644 --- a/docs/code-quality/c26449.md +++ b/docs/code-quality/c26449.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Warning C26449 NO_SPAN_FROM_TEMPORARY" title: Warning C26449 -ms.date: 03/22/2018 +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"] --- @@ -9,9 +9,11 @@ helpviewer_keywords: ["C26449"] > `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 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. There's another check that handles a 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 @@ -38,7 +40,7 @@ Subtle difference in result types: gsl::span get_seed_sequence() noexcept; // Returns a generated collection. Doesn't own new data. -const std::vector get_next_sequence(gsl::span); +std::vector get_next_sequence(gsl::span); void run_batch() { @@ -50,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 7fc48fb269..66044efb23 100644 --- a/docs/code-quality/c26450.md +++ b/docs/code-quality/c26450.md @@ -1,23 +1,23 @@ --- -description: "Learn more about: Arithmetic overflow: '%operator%' operation causes overflow at compile time. Use a wider type to store the operands" title: Warning C26450 -ms.date: 01/08/2017 +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"] --- # Warning C26450 ->Arithmetic overflow: '*operator*' operation causes overflow at compile time. Use a wider type to store the operands (io.1) +> Arithmetic overflow: '*operator*' operation causes overflow at compile time. Use a wider type to store the operands (io.1) ## Remarks 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 is a similar check in the Microsoft C++ compiler. +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` -## Example 1 +## Examples ```cpp int multiply() @@ -36,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 2c2af3a147..0067e42718 100644 --- a/docs/code-quality/c26451.md +++ b/docs/code-quality/c26451.md @@ -1,7 +1,7 @@ --- 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.date: 05/11/2023 f1_keywords: ["C26451", "RESULT_OF_ARITHMETIC_OPERATION_CAST_TO_LARGER_SIZE"] helpviewer_keywords: ["C26451"] --- @@ -17,14 +17,14 @@ Code analysis detects when an integral value gets shifted left, multiplied, adde Code analysis name: `RESULT_OF_ARITHMETIC_OPERATION_CAST_TO_LARGER_SIZE` -## Example 1 +## 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 6d54b5b539..0f529f60ce 100644 --- a/docs/code-quality/c26452.md +++ b/docs/code-quality/c26452.md @@ -13,14 +13,14 @@ helpviewer_keywords: ["C26452"] 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. -Warning 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 } @@ -29,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 } @@ -37,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 5c2a61ce75..32a7064209 100644 --- a/docs/code-quality/c26453.md +++ b/docs/code-quality/c26453.md @@ -1,7 +1,7 @@ --- 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.date: 05/11/2023 f1_keywords: ["C26453", "LEFTSHIFT_NEGATIVE_SIGNED_NUMBER"] helpviewer_keywords: ["C26453"] --- @@ -11,7 +11,7 @@ helpviewer_keywords: ["C26453"] ## Remarks -This warning indicates the code left shifts a negative signed integral value, which is non-portable and triggers implementation defined behavior. +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` @@ -31,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 } @@ -39,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 4610dc5cb6..77b21092ec 100644 --- a/docs/code-quality/c26454.md +++ b/docs/code-quality/c26454.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Arithmetic overflow: 'operator' operation produces a negative unsigned result at compile time" title: Warning C26454 +description: "Learn more about: Arithmetic overflow: 'operator' operation produces a negative unsigned result at compile time" ms.date: 01/08/2017 f1_keywords: ["C26454", "RESULT_OF_ARITHMETIC_OPERATION_NEGATIVE_UNSIGNED"] helpviewer_keywords: ["C26454"] @@ -37,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 51501d72b9..617f0cedd5 100644 --- a/docs/code-quality/c26455.md +++ b/docs/code-quality/c26455.md @@ -1,10 +1,9 @@ --- -description: "Learn more about the C26455 DEFAULT_CTOR_NOEXCEPT C++ Core Guidelines Checker warning. Default constructors shouldn't do anything that can throw." 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 @@ -13,7 +12,7 @@ ms.custom: kr2b-contr-experiment > 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. 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. +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 @@ -23,4 +22,5 @@ Code analysis name: `DEFAULT_CTOR_NOEXCEPT` ## See also -- [C++ Core Guideline F.6](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/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 b85910ae52..2307b0d592 100644 --- a/docs/code-quality/c26460.md +++ b/docs/code-quality/c26460.md @@ -24,7 +24,6 @@ struct MyStruct void MemberFn2(); }; - void Function1_Helper(const MyStruct&); void Function1(MyStruct& myStruct) // C26460, see comments below. { diff --git a/docs/code-quality/c26478.md b/docs/code-quality/c26478.md index 23d897a01c..ddaff2f01b 100644 --- a/docs/code-quality/c26478.md +++ b/docs/code-quality/c26478.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Warning C26478: Don't use std::move on constant variables. (es.56)" title: Warning C26478 -ms.date: 07/15/2019 +description: "Learn more about: Warning C26478: Don't use std::move on constant variables. (es.56)" +ms.date: 10/12/2023 f1_keywords: ["C26478", "NO_MOVE_OP_ON_CONST"] helpviewer_keywords: ["C26478"] --- @@ -13,11 +13,11 @@ helpviewer_keywords: ["C26478"] This warning is to indicate that the use of `std::move` not consistent with how `std::move` is intended to be used. -When called on a `const` object, `std::move` returns a copy of the object, which is likely not the developer's intent. +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 1 +## Example ```cpp struct node @@ -33,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/c26483.md b/docs/code-quality/c26483.md index ea4c10c6b9..5e031b2448 100644 --- a/docs/code-quality/c26483.md +++ b/docs/code-quality/c26483.md @@ -1,9 +1,9 @@ --- title: Warning C26483 +description: CppCoreCheck rule C26483 that enforces C++ Core Guidelines Bounds.2 ms.date: 03/22/2018 f1_keywords: ["C26483", "STATIC_INDEX_OUT_OF_RANGE"] helpviewer_keywords: ["C26483"] -description: CppCoreCheck rule C26483 that enforces C++ Core Guidelines Bounds.2 --- # Warning C26483 @@ -24,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/c26488.md b/docs/code-quality/c26488.md index b3ae0ce888..a54608facb 100644 --- a/docs/code-quality/c26488.md +++ b/docs/code-quality/c26488.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Warning C26488 LIFETIMES_DEREF_NULL_POINTER" title: Warning C26488 +description: "Learn more about: Warning C26488 LIFETIMES_DEREF_NULL_POINTER" ms.date: 12/14/2018 f1_keywords: ["C26488", "LIFETIMES_DEREF_NULL_POINTER"] helpviewer_keywords: ["C26488"] -ms.assetid: 2ade0d31-f259-49de-8676-cce6092fabfc author: kylereedmsft ms.author: kylereed --- @@ -28,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 2f252dc766..85df9e569a 100644 --- a/docs/code-quality/c26489.md +++ b/docs/code-quality/c26489.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Warning C26489 LIFETIMES_DEREF_INVALID_POINTER" title: Warning C26489 +description: "Learn more about: Warning C26489 LIFETIMES_DEREF_INVALID_POINTER" ms.date: 12/14/2018 f1_keywords: ["C26489", "LIFETIMES_DEREF_INVALID_POINTER"] helpviewer_keywords: ["C26489"] -ms.assetid: 15983d4f-f615-42e7-8521-ee094b87d066 author: kylereedmsft ms.author: kylereed --- @@ -30,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/c26494.md b/docs/code-quality/c26494.md index 41cfa16b20..7ed21fb002 100644 --- a/docs/code-quality/c26494.md +++ b/docs/code-quality/c26494.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Warning C26494 VAR_USE_BEFORE_INIT" title: Warning C26494 +description: "Learn more about: Warning C26494 VAR_USE_BEFORE_INIT." ms.date: 03/22/2018 f1_keywords: ["C26494", "VAR_USE_BEFORE_INIT"] helpviewer_keywords: ["C26494"] @@ -9,9 +9,9 @@ helpviewer_keywords: ["C26494"] > 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 @@ -23,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 f433277553..f99e5697b8 100644 --- a/docs/code-quality/c26495.md +++ b/docs/code-quality/c26495.md @@ -1,9 +1,9 @@ --- title: Warning C26495 -ms.date: 08/18/2022 +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 --- # Warning C26495 @@ -13,7 +13,9 @@ description: CppCoreCheck rule that enforces C++ Core Guidelines Type.6 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). -Code analysis name: MEMBER_UNINIT +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 @@ -36,3 +38,7 @@ struct MyStruct 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/c26498.md b/docs/code-quality/c26498.md index 064ef2b92d..e495372145 100644 --- a/docs/code-quality/c26498.md +++ b/docs/code-quality/c26498.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Warning C26498 USE_CONSTEXPR_FOR_FUNCTIONCALL" title: Warning C26498 +description: "Learn more about: Warning C26498 USE_CONSTEXPR_FOR_FUNCTIONCALL" ms.date: 08/18/2020 f1_keywords: ["C26498", "USE_CONSTEXPR_FOR_FUNCTIONCALL"] helpviewer_keywords: ["C26498"] @@ -9,15 +9,17 @@ helpviewer_keywords: ["C26498"] > The function '*function*' is constexpr, mark variable '*variable*' constexpr if compile-time evaluation is desired (con.5) -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. +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() @@ -34,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 9e0328095e..1052f0f0db 100644 --- a/docs/code-quality/c26800.md +++ b/docs/code-quality/c26800.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Warning C26800" title: Warning C26800 +description: "Learn more about: Warning C26800" ms.date: 01/14/2019 f1_keywords: ["C26800", "USE_OF_A_MOVED_FROM_OBJECT"] helpviewer_keywords: ["C26800"] @@ -11,13 +11,42 @@ helpviewer_keywords: ["C26800"] ## Remarks -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`. +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 + +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 will generate C26800. +The following code generates C26800. ```cpp #include @@ -37,11 +66,11 @@ 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 won't generate C26800. +The following code doesn't generate C26800. ```cpp #include diff --git a/docs/code-quality/c26810.md b/docs/code-quality/c26810.md index 903b6d4d0c..95c9c83644 100644 --- a/docs/code-quality/c26810.md +++ b/docs/code-quality/c26810.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Warning C26810" title: Warning C26810 -ms.date: 01/14/2019 +description: "Learn more about: Warning C26810." +ms.date: 05/11/2023 f1_keywords: ["C26810", "COROUTINES_USE_AFTER_FREE_CAPTURE"] helpviewer_keywords: ["C26810"] --- @@ -11,13 +11,13 @@ helpviewer_keywords: ["C26810"] ## Remarks -Warning C26810 is triggered when a memory region might be used after it went out of scope in a resumed coroutine. +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 @@ -66,4 +66,4 @@ Alternatively, if the coroutine is guaranteed to live shorter than the lambda ob ## 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 9e2d4808d3..ebdc5bcc40 100644 --- a/docs/code-quality/c26811.md +++ b/docs/code-quality/c26811.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Warning C26811" title: Warning C26811 -ms.date: 01/14/2019 +description: "Learn more about: Warning C26811." +ms.date: 05/11/2023 f1_keywords: ["C26811", "COROUTINES_USE_AFTER_FREE_PARAM"] helpviewer_keywords: ["C26811"] --- @@ -11,13 +11,13 @@ helpviewer_keywords: ["C26811"] ## Remarks -Warning C26811 is triggered when a memory region might be used after it went out of scope in a resumed coroutine. +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 @@ -58,4 +58,4 @@ Alternatively, when the lifetime of `a` is guaranteed to outlive the lifetime of ## See also -- [C26810](../code-quality/c26810.md) +[C26810](c26810.md) diff --git a/docs/code-quality/c26813.md b/docs/code-quality/c26813.md index 61ddbb60b7..eabce1bfec 100644 --- a/docs/code-quality/c26813.md +++ b/docs/code-quality/c26813.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Warning C26813" title: Warning C26813 -ms.date: 03/02/2022 +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"] --- diff --git a/docs/code-quality/c26815.md b/docs/code-quality/c26815.md index 3995dff0a2..5a8c319b65 100644 --- a/docs/code-quality/c26815.md +++ b/docs/code-quality/c26815.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Warning C26815 The pointer is dangling because it points at a temporary instance that was destroyed. (ES.65)" title: Warning C26815 +description: "Learn more about: Warning C26815." author: Rastaban ms.author: philc ms.date: 01/27/2020 @@ -13,12 +13,17 @@ helpviewer_keywords: ["C26815"] ## Remarks -There's a dangling pointer that is the result of an unnamed temporary that has been destroyed. +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(); @@ -36,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. @@ -57,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 9f16cf956d..f60d02ef09 100644 --- a/docs/code-quality/c26816.md +++ b/docs/code-quality/c26816.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Warning C26816 The pointer points to memory allocated on the stack (ES.65)" title: Warning C26816 +description: "Learn more about: Warning C26816." author: Rastaban ms.author: philc ms.date: 01/27/2020 @@ -15,9 +15,12 @@ helpviewer_keywords: ["C26816"] 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` -## Example +## Examples ```cpp // In this example, std::string is being used internally because the implementer felt it was easier to @@ -27,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 } ``` @@ -42,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 2c61af2727..3e66b660cf 100644 --- a/docs/code-quality/c26817.md +++ b/docs/code-quality/c26817.md @@ -1,7 +1,7 @@ --- title: Warning C26817 description: "Reference for Microsoft C++ Code Analysis warning C26817 in Visual Studio." -ms.date: 02/24/2020 +ms.date: 10/12/2023 f1_keywords: ["C26817"] helpviewer_keywords: ["C26817"] --- @@ -9,7 +9,7 @@ helpviewer_keywords: ["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 @@ -25,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 // ... @@ -38,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: @@ -67,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/c26819.md b/docs/code-quality/c26819.md index dc8713deb5..fea652f765 100644 --- a/docs/code-quality/c26819.md +++ b/docs/code-quality/c26819.md @@ -13,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(); @@ -27,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: @@ -39,8 +39,6 @@ void foo(int a) } ``` -## Solution - To fix this issue, insert a `[[fallthrough]];` statement where the fallthrough occurs. ```cpp @@ -86,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 926ec23bf1..133edaf130 100644 --- a/docs/code-quality/c26820.md +++ b/docs/code-quality/c26820.md @@ -1,17 +1,17 @@ --- 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"] --- # 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/c26826.md b/docs/code-quality/c26826.md index 8c0f827e9d..47fd2d9e8d 100644 --- a/docs/code-quality/c26826.md +++ b/docs/code-quality/c26826.md @@ -9,7 +9,7 @@ helpviewer_keywords: ["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 diff --git a/docs/code-quality/c26827.md b/docs/code-quality/c26827.md index 4fa10fc07f..7f80abb532 100644 --- a/docs/code-quality/c26827.md +++ b/docs/code-quality/c26827.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Warning C26827" title: Warning C26827 -ms.date: 03/02/2022 +description: "Learn more about: Warning C26827" +ms.date: 05/17/2023 f1_keywords: ["C26827", "ALMOST_BITWISE_ENUM"] helpviewer_keywords: ["C26827"] --- diff --git a/docs/code-quality/c26828.md b/docs/code-quality/c26828.md index ee3f102c2c..5c0a9d474d 100644 --- a/docs/code-quality/c26828.md +++ b/docs/code-quality/c26828.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Warning C26828" title: Warning C26828 -ms.date: 03/02/2022 +description: "Learn more about: Warning C26828" +ms.date: 05/17/2023 f1_keywords: ["C26828", "MIXING_OVERLAPPING_ENUMS"] helpviewer_keywords: ["C26828"] --- 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/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 d3597bd143..927e462bda 100644 --- a/docs/code-quality/c28020.md +++ b/docs/code-quality/c28020.md @@ -1,15 +1,32 @@ --- -description: "Learn more about: Warning C28020" title: Warning C28020 -ms.date: 11/04/2016 +description: "Learn more about: Warning C28020" +ms.date: 03/25/2025 f1_keywords: ["C28020"] helpviewer_keywords: ["C28020"] -ms.assetid: 3612185a-0858-4ba9-b795-4a0681073cf7 --- # Warning C28020 -> The expression '*expr*' is not true at this call +> The expression '*expr*' is not true at this call. This warning is reported when the `_Satisfies_` expression listed isn't true. Frequently, the warning indicates an incorrect parameter. 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/c28112.md b/docs/code-quality/c28112.md index 74c567f97d..530ab51bc0 100644 --- a/docs/code-quality/c28112.md +++ b/docs/code-quality/c28112.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Warning 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 --- # Warning C28112 @@ -16,7 +15,7 @@ A variable that is accessed by using the Interlocked executive support routines, `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 +Code analysis name: `INTERLOCKED_ACCESS` ## Example @@ -38,5 +37,5 @@ InterlockedIncrement(&inter_var); ## See Also -[InterlockedIncrement function (wdm.h)](/windows-hardware/drivers/ddi/wdm/nf-wdm-interlockedincrement) +[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/c28159.md b/docs/code-quality/c28159.md index e17a31ee6f..05fbe31944 100644 --- a/docs/code-quality/c28159.md +++ b/docs/code-quality/c28159.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Warning 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 --- # Warning C28159 -> Consider using `*function_name_1*` instead of `*function_name_2*`. Reason: *reason* +> Consider using *`function_name_1`* instead of *`function_name_2`*. Reason: *reason* This warning occurs when you use a function that is semantically equivalent to an alternative, preferred function call. @@ -16,7 +15,7 @@ This warning occurs when you use a function that is semantically equivalent to a 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 +Code analysis name: `USE_OTHER_FUNCTION` ## Example diff --git a/docs/code-quality/c28160.md b/docs/code-quality/c28160.md index 38ea9be0b1..eeee7046da 100644 --- a/docs/code-quality/c28160.md +++ b/docs/code-quality/c28160.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Warning 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 --- # Warning C28160 @@ -16,4 +15,4 @@ 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. -Code analysis name: ERROR +Code analysis name: `ERROR` diff --git a/docs/code-quality/c28196.md b/docs/code-quality/c28196.md index e6f445f94c..388766230a 100644 --- a/docs/code-quality/c28196.md +++ b/docs/code-quality/c28196.md @@ -1,13 +1,53 @@ --- -description: "Learn more about: Warning C28196" title: Warning C28196 +description: "Learn more about: Warning C28196" ms.date: 11/04/2016 -f1_keywords: ["C28196"] +f1_keywords: ["C28196", "RETURNING_BAD_RESULT", "__WARNING_RETURNING_BAD_RESULT"] helpviewer_keywords: ["C28196"] -ms.assetid: 5ee89e96-2796-4316-a64c-702463ca1374 --- # Warning C28196 > 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/c28213.md b/docs/code-quality/c28213.md index 8fe4482890..0703a653b8 100644 --- a/docs/code-quality/c28213.md +++ b/docs/code-quality/c28213.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Warning C28213" title: Warning C28213 -ms.date: 09/08/2022 +ms.date: 02/07/2023 f1_keywords: ["C28213", "BAD_USEHEADER", "__WARNING_BAD_USEHEADER"] helpviewer_keywords: ["C28213"] -ms.assetid: e141a12a-4c46-47eb-aa9d-a6444472cfaa --- # Warning C28213 @@ -12,44 +11,62 @@ ms.assetid: e141a12a-4c46-47eb-aa9d-a6444472cfaa ## Remarks -`_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, then this warning is emitted. +`_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. -Code analysis name: BAD_USEHEADER +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). -## Example +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 -void example_func(_Out_writes_(n) char* buffer, int n); +void addNullTerminate(_Out_writes_(n) char* buffer, int n); ``` *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'; } ``` -This issue 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'll move that to the function declaration in the header file. The following code resolves this warning: +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 example_func(_Out_writes_z_(n) char* buffer, int n); +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.cpp:* ```cpp _Use_decl_annotations_ -void example_func(_Out_writes_z_(n) char* buffer, int n) +void addNullTerminate(char* buffer, int n) { 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/c28306.md b/docs/code-quality/c28306.md index 6f1641b1a3..0462d5856d 100644 --- a/docs/code-quality/c28306.md +++ b/docs/code-quality/c28306.md @@ -11,3 +11,7 @@ ms.assetid: 64517b10-c8b3-4100-953b-278eab624369 > 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 672d1f5793..28d5af3d02 100644 --- a/docs/code-quality/c28307.md +++ b/docs/code-quality/c28307.md @@ -11,3 +11,7 @@ ms.assetid: e86a14cc-9ff1-4bad-9d85-93c739704ab8 > 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 2d1f139a6c..c4ceffa743 100644 --- a/docs/code-quality/c28308.md +++ b/docs/code-quality/c28308.md @@ -1,21 +1,50 @@ --- description: "Learn more about: Warning C28308" title: Warning C28308 -ms.date: 11/04/2016 -f1_keywords: ["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 --- # Warning C28308 > 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/c28310.md b/docs/code-quality/c28310.md index 4b85718201..30aa4d8244 100644 --- a/docs/code-quality/c28310.md +++ b/docs/code-quality/c28310.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Warning C28310" title: Warning C28310 +description: "Learn more about: Warning C28310" ms.date: 11/04/2016 f1_keywords: ["C28310"] -ms.assetid: 51054ca8-01b6-454b-9853-f05f1c817b18 +helpviewer_keywords: ["C28310"] --- # Warning C28310 diff --git a/docs/code-quality/c28311.md b/docs/code-quality/c28311.md index 70e03e716e..9d72006cae 100644 --- a/docs/code-quality/c28311.md +++ b/docs/code-quality/c28311.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Warning C28311" title: Warning C28311 +description: "Learn more about: Warning C28311" ms.date: 11/04/2016 f1_keywords: ["C28311"] -ms.assetid: 2c76e07a-4418-40ef-8a77-c62774bc3677 +helpviewer_keywords: ["C28311"] --- # Warning C28311 diff --git a/docs/code-quality/c28312.md b/docs/code-quality/c28312.md index 55f6154d54..852d5bec16 100644 --- a/docs/code-quality/c28312.md +++ b/docs/code-quality/c28312.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Warning C28312" title: Warning C28312 +description: "Learn more about: Warning C28312" ms.date: 11/04/2016 f1_keywords: ["C28312"] -ms.assetid: 19828546-33c9-4373-b7df-2a362ca12637 +helpviewer_keywords: ["C28312"] --- # Warning C28312 diff --git a/docs/code-quality/c33001.md b/docs/code-quality/c33001.md index d3208941b4..679ffc1e04 100644 --- a/docs/code-quality/c33001.md +++ b/docs/code-quality/c33001.md @@ -13,14 +13,23 @@ helpviewer_keywords: ["C33001"] ## Remarks -This warning is triggered when an uninitialized `VARIANT` is passed to an API such as `VariantClear` -that expects an initialized `VARIANT`. +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 sample code causes warning C33001: +The following code causes warning C33001: ```cpp #include @@ -36,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 @@ -54,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 752103c945..44486d8ffc 100644 --- a/docs/code-quality/c33004.md +++ b/docs/code-quality/c33004.md @@ -49,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 8c056ba671..41509513e3 100644 --- a/docs/code-quality/c33005.md +++ b/docs/code-quality/c33005.md @@ -55,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 b9e5fa937d..e4c4a598df 100644 --- a/docs/code-quality/c33010.md +++ b/docs/code-quality/c33010.md @@ -9,7 +9,7 @@ helpviewer_keywords: ["C33010"] --- # Warning C33010 -> Unchecked lower bound for enum *enum_name* used as index. +> Unchecked lower bound for enum 'enum' used as index. This warning is triggered if an enum is both used as an index into an array and isn't checked on the lower bound. @@ -71,6 +71,31 @@ void foo(Index idx, PFN(&functions)[5]) } ``` +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)(); +} +``` + ## See also [C33011](./c33011.md) diff --git a/docs/code-quality/c33011.md b/docs/code-quality/c33011.md index f38913b3f2..f2087f89c8 100644 --- a/docs/code-quality/c33011.md +++ b/docs/code-quality/c33011.md @@ -4,7 +4,7 @@ description: C33011 warning for enums author: hwisungi ms.author: hwisungi ms.date: 06/20/2020 -f1_keywords: ["C33011", "UNCHECKED_UPPER_BOUND_FOR_ENUMINDEX"] +f1_keywords: ["C33011", "UNCHECKED_UPPER_BOUND_FOR_ENUMINDEX", "__WARNING_UNCHECKED_UPPER_BOUND_FOR_ENUMINDEX"] helpviewer_keywords: ["C33011"] --- # Warning C33011 diff --git a/docs/code-quality/c6001.md b/docs/code-quality/c6001.md index 571cf38dfb..755bb88cb3 100644 --- a/docs/code-quality/c6001.md +++ b/docs/code-quality/c6001.md @@ -4,7 +4,6 @@ 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 --- # Warning C6001 @@ -18,7 +17,7 @@ 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 ) @@ -37,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 da1329fb26..2094f73796 100644 --- a/docs/code-quality/c6011.md +++ b/docs/code-quality/c6011.md @@ -64,6 +64,27 @@ 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). +## 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) @@ -71,3 +92,5 @@ The careless use of `malloc` and `free` leads to memory leaks and exceptions. To - [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) +- [`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 b950ef16b3..9806124fb8 100644 --- a/docs/code-quality/c6014.md +++ b/docs/code-quality/c6014.md @@ -97,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()); diff --git a/docs/code-quality/c6029.md b/docs/code-quality/c6029.md index 6638b8912d..729f39ab08 100644 --- a/docs/code-quality/c6029.md +++ b/docs/code-quality/c6029.md @@ -1,82 +1,92 @@ --- -description: "Learn more about: Warning C6029" title: Warning C6029 -ms.date: 10/04/2022 +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 --- # Warning C6029 -> Possible buffer overrun in call to '*function*': use of unchecked value +> Possible buffer overrun in call to '*function*' -## Remarks +Possible buffer overrun in called function due to an unchecked buffer length/size parameter. -This warning indicates that a function that takes a buffer and a size is being passed an unchecked size. The data read-in from some external source hasn't been verified to see whether it's 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. +## Remarks -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. +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 -#include "windows.h" +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); +} +``` + +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)) + if (dataSize > MAX_BUFFER_SIZE) { - return false; - } - // Read the bytes - if (!ReadFile (hFile, buff, cbLen, &cbRead, NULL)) // warning C6029 - { - 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 5a6627f664..541fca4ba5 100644 --- a/docs/code-quality/c6031.md +++ b/docs/code-quality/c6031.md @@ -1,10 +1,9 @@ --- title: Warning C6031 description: "Describes C++ Code Analysis warning C6031 and how to resolve it." -ms.date: 10/04/2022 +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 --- # Warning C6031 @@ -16,44 +15,48 @@ Warning C6031 indicates the caller doesn't check a function's return value for f 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 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 ... } @@ -64,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(); } ``` @@ -76,11 +82,15 @@ 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 ... } } @@ -91,10 +101,12 @@ In cases where it's necessary to ignore the return value of a function, assign t ```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 06943ee97c..426980c787 100644 --- a/docs/code-quality/c6053.md +++ b/docs/code-quality/c6053.md @@ -69,7 +69,9 @@ 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 diff --git a/docs/code-quality/c6059.md b/docs/code-quality/c6059.md index 8a12022eb0..d78c0f3f74 100644 --- a/docs/code-quality/c6059.md +++ b/docs/code-quality/c6059.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Warning C6059" title: Warning C6059 -ms.date: 10/04/2022 +ms.date: 12/14/2023 f1_keywords: ["C6059", "BAD_CONCATENATION", "__WARNING_BAD_CONCATENATION"] helpviewer_keywords: ["C6059"] ms.assetid: 343a4cd1-048a-4edf-bb4b-187097bb6093 @@ -14,6 +14,8 @@ ms.assetid: 343a4cd1-048a-4edf-bb4b-187097bb6093 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 @@ -27,8 +29,8 @@ The following code generates warning C6059: void f( ) { char szTarget[MAX]; - char *szState ="Washington"; - char *szCity="Redmond, "; + const char *szState ="Washington"; + const char *szCity="Redmond, "; strncpy(szTarget, szCity, MAX); szTarget[MAX -1] = '\0'; @@ -46,8 +48,8 @@ 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); szTarget[MAX -1] = '\0'; @@ -63,8 +65,8 @@ To correct this warning using the safe string manipulation functions `strncpy_s` 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]; @@ -77,6 +79,48 @@ 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) diff --git a/docs/code-quality/c6063.md b/docs/code-quality/c6063.md index e1c140c02b..e84940d4b2 100644 --- a/docs/code-quality/c6063.md +++ b/docs/code-quality/c6063.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Warning C6063" title: Warning C6063 -ms.date: 10/04/2022 +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 --- # Warning C6063 @@ -21,7 +20,7 @@ Code analysis name: `MISSING_STRING_ARGUMENT_TO_FORMAT_FUNCTION` The following code generates this warning: ```cpp -#include +#include void f( ) { char buff[15]; @@ -29,10 +28,10 @@ void f( ) } ``` -To correct this warning, provide the required 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]; @@ -43,7 +42,7 @@ void f( ) The following code corrects this warning using safe string manipulation function: ```cpp -#include +#include void f( ) { char buff[15]; @@ -53,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 daec769cd9..645f77ff24 100644 --- a/docs/code-quality/c6064.md +++ b/docs/code-quality/c6064.md @@ -1,16 +1,15 @@ --- description: "Learn more about: Warning C6064" title: Warning C6064 -ms.date: 10/03/2022 +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 --- # Warning C6064 > Missing integer argument to '*function-name*' corresponding to conversion specifier '*number*' -This warning indicates that not enough arguments are provided to match a format string and one of the missing arguments is an integer. +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. ## Remarks @@ -20,13 +19,13 @@ Code analysis name: `MISSING_INTEGER_ARGUMENT_TO_FORMAT_FUNCTION` ## Example -The following code generates this warning because an incorrect number of arguments were used in the call to `sprintf_s` and the missing argument was 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: +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 void f() { char buff[8]; - char *string="Hello"; + 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 @@ -35,17 +34,18 @@ void f() } ``` -To correct this warning, specify missing arguments as shown in the following code: +To correct this warning, specify missing arguments or adjust the format string. In this example, we add the missing integer value. ```cpp void f() { char buff[8]; - char *string = "Hello"; + 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 a411356bad..8ae5f79902 100644 --- a/docs/code-quality/c6066.md +++ b/docs/code-quality/c6066.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Warning C6066" title: Warning C6066 -ms.date: 10/04/2022 +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 --- # Warning C6066 @@ -32,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 ... } ``` @@ -47,15 +45,12 @@ 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 ... } ``` @@ -66,15 +61,12 @@ The following code uses safe string manipulation functions `sprintf_s` and `scan 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 ... } ``` @@ -83,5 +75,8 @@ This warning is typically reported because an integer has been used for a `%p` f ## 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 23c357ded8..0a181ff13a 100644 --- a/docs/code-quality/c6067.md +++ b/docs/code-quality/c6067.md @@ -1,15 +1,16 @@ --- description: "Learn more about: Warning C6067" title: Warning C6067 -ms.date: 11/04/2016 +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 --- # Warning C6067 > 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. @@ -26,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 ... } ``` @@ -98,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 ece119dd0d..ee653b08a8 100644 --- a/docs/code-quality/c6101.md +++ b/docs/code-quality/c6101.md @@ -1,38 +1,86 @@ --- description: "Learn more about: Warning C6101" title: Warning C6101 -ms.date: 08/17/2022 +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 --- # Warning C6101 -> Returning uninitialized memory '*parameter-name*'. A successful path through the function does not set the named `_Out_` parameter. +> Returning uninitialized memory '*parameter-name*'. + +A successful path through the function doesn't set the `_Out_` annotated parameter. ## Remarks -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, however, the function does indicate success/failure and failure occurs, then the `_Out_` parameter doesn't have to be set. You can then 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 later 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). +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. This issue stems from the pointer p1 not being set despite having been annotated with `_Out_`. +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 -void example_func(_Out_ int *p1) +#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 resolve the issue, you can set the value of the parameter. Or, if the value is always initialized before the function is called, change the SAL annotation to `_Inout_`. By setting the value of the parameter, the following code avoids the warning: +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 -void example_func(_Out_ int *p1) +_Success_(return == true) +bool InitNotZero(_Out_ int* output, int input) { - *p1 = 1; - return; + 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 d1dd840a69..9c35f2bc5a 100644 --- a/docs/code-quality/c6102.md +++ b/docs/code-quality/c6102.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Warning C6102" title: Warning C6102 +description: "Learn more about: Warning C6102" ms.date: 11/04/2016 f1_keywords: ["C6102"] -ms.assetid: cfd49a8c-df46-48de-8dcb-02ecf2450034 +helpviewer_keywords: ["C6102"] --- # Warning C6102 diff --git a/docs/code-quality/c6103.md b/docs/code-quality/c6103.md index d348b72bd5..6c9dfdcfcd 100644 --- a/docs/code-quality/c6103.md +++ b/docs/code-quality/c6103.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Warning C6103" title: Warning C6103 +description: "Learn more about: Warning C6103" ms.date: 11/04/2016 f1_keywords: ["C6103"] -ms.assetid: 22d1ab35-31a3-4ba9-8ef4-7a64bce66621 +helpviewer_keywords: ["C6103"] --- # Warning C6103 diff --git a/docs/code-quality/c6200.md b/docs/code-quality/c6200.md index 8c2ddee479..2106582d1a 100644 --- a/docs/code-quality/c6200.md +++ b/docs/code-quality/c6200.md @@ -8,9 +8,9 @@ ms.assetid: bbeb159b-4e97-4317-9a07-bb83cd03069a --- # Warning C6200 -> Index '*index*' is out of valid index range '*min*' to '*max*' for non-stack buffer '*parameter-name*' +> 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 non-stack array exceeds the maximum bounds of that array, potentially causing random behavior and/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 @@ -47,3 +47,27 @@ void f() 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 30ca1e6f2f..85118a0503 100644 --- a/docs/code-quality/c6201.md +++ b/docs/code-quality/c6201.md @@ -1,16 +1,15 @@ --- description: "Learn more about: Warning C6201" title: Warning C6201 -ms.date: 09/28/2022 +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 --- # Warning C6201 > 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. It may potentially cause stack overflow errors, 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 @@ -45,3 +44,9 @@ void f() } } ``` + +## 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/c6217.md b/docs/code-quality/c6217.md index 6da8bfef42..410cfb0fa5 100644 --- a/docs/code-quality/c6217.md +++ b/docs/code-quality/c6217.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Warning C6217" title: Warning C6217 -ms.date: 11/04/2016 +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 --- # Warning C6217 @@ -12,13 +11,17 @@ ms.assetid: 93ac7ce2-c27b-4b3a-9a98-72f26fcf1def ## Remarks -This warning indicates that an `HRESULT` is being tested with the logical-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 logical-not operator (`!`) to determine which code block to run can cause following the wrong code path. This test will lead to unwanted results. +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 logical-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 @@ -38,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 @@ -58,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's 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/c6240.md b/docs/code-quality/c6240.md index d50c2ba072..1e44d46db2 100644 --- a/docs/code-quality/c6240.md +++ b/docs/code-quality/c6240.md @@ -53,7 +53,7 @@ void f(int n) } else { - puts("bitmak false"); + puts("bitmask false"); } } ``` diff --git a/docs/code-quality/c6270.md b/docs/code-quality/c6270.md index a2b0d71d0a..6a23a7f305 100644 --- a/docs/code-quality/c6270.md +++ b/docs/code-quality/c6270.md @@ -1,20 +1,17 @@ --- description: "Learn more about: Warning C6270" title: Warning C6270 -ms.date: 10/03/2022 +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 --- # Warning C6270 > Missing float argument to '*function-name*': add a float argument corresponding to conversion specifier '*number*' -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. - ## Remarks -This defect can lead to crashes, in addition to potentially incorrect output. +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. Code analysis name: `MISSING_FLOAT_ARGUMENT_TO_FORMAT_FUNCTION` @@ -42,5 +39,7 @@ void f() ## See also +[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) +[`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 cf822df25e..29c2626788 100644 --- a/docs/code-quality/c6271.md +++ b/docs/code-quality/c6271.md @@ -1,18 +1,17 @@ --- description: "Learn more about: Warning C6271" title: Warning C6271 -ms.date: 11/04/2016 +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 --- # Warning C6271 -> Extra argument passed to '*function*': parameter '*number*' is not used by the format string +> Extra argument passed to '*function*' ## Remarks -This warning indicates that additional arguments are being provided beyond the ones specified by the format string. By itself, this defect won't have any visible effect although it indicates that the programmer's intent isn't reflected in the code. +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` @@ -22,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); } ``` @@ -50,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 aa1f34f16a..5a25de9b99 100644 --- a/docs/code-quality/c6272.md +++ b/docs/code-quality/c6272.md @@ -1,20 +1,17 @@ --- description: "Learn more about: Warning C6272" title: Warning C6272 -ms.date: 09/15/2022 +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 --- # Warning C6272 > 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. - ## Remarks -This defect is likely to result in incorrect output and, in certain circumstances, could result in a crash. +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. Code analysis name: `NON_FLOAT_ARGUMENT_TO_FORMAT_FUNCTION` @@ -31,7 +28,7 @@ void f() } ``` -To correct this warning, use `%i` instead of `%f` specification as shown in the following code: +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 void f() @@ -41,3 +38,10 @@ void f() sprintf_s(buff, sizeof(buff), "%s %i", "a", i); } ``` + +## See also + +[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 1b3dc4d071..7bf741fbf4 100644 --- a/docs/code-quality/c6273.md +++ b/docs/code-quality/c6273.md @@ -1,18 +1,17 @@ --- description: "Learn more about: Warning C6273" title: Warning C6273 -ms.date: 11/04/2016 +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 --- # Warning C6273 -> Non-integer passed as parameter '*number*' when integer is required in call to '*function*': 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*' ## Remarks -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. +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` @@ -22,7 +21,6 @@ The following code generates this warning because an integer is required instead ```cpp #include -#include void f_defective() { @@ -33,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() { @@ -52,7 +49,6 @@ The following code uses safe string manipulation function, `sprintf_s`, to corre ```cpp #include -#include void f_safe() { @@ -67,4 +63,6 @@ This warning isn't applicable on Windows 9x and Windows NT version 4 because %p ## 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 f746c01427..7941289172 100644 --- a/docs/code-quality/c6274.md +++ b/docs/code-quality/c6274.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Warning C6274" title: Warning C6274 -ms.date: 11/04/2016 +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 --- # Warning C6274 @@ -22,12 +21,10 @@ The following code generates this warning: ```cpp #include -#include void f(char str[]) { char buff[5]; - sprintf(buff,"%c",str); } ``` @@ -36,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]); } ``` @@ -50,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/c6284.md b/docs/code-quality/c6284.md index 693e8518bd..4c29d20e33 100644 --- a/docs/code-quality/c6284.md +++ b/docs/code-quality/c6284.md @@ -1,22 +1,19 @@ --- description: "Learn more about: Warning C6284" title: Warning C6284 -ms.date: 11/04/2016 +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 --- # Warning C6284 > Object passed as parameter when string is required in call to '*function\*' -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 matched with it's an object type. - -This defect might produce incorrect output or a crash. - ## Remarks -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 parameters to `printf`-style functions are essentially untyped, so no automatic conversion occurs. +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 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` @@ -25,7 +22,6 @@ Code analysis name: `OBJECT_AS_STRING_ARGUMENT_TO_FORMAT_FUNCTION` ```cpp #include #include -#include void f() { @@ -34,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); } ``` @@ -43,7 +39,6 @@ Fix the warning by adding the appropriate conversions: ```cpp #include #include -#include void f() { @@ -52,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/c6296.md b/docs/code-quality/c6296.md index c5b5b21acb..e6f7da0340 100644 --- a/docs/code-quality/c6296.md +++ b/docs/code-quality/c6296.md @@ -1,47 +1,35 @@ --- -description: "Learn more about: Warning C6296" title: Warning C6296 -ms.date: 11/04/2016 +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 --- # Warning C6296 -> Ill-defined for-loop: Loop body only executed once +> Ill-defined for-loop. Loop body only executed once. ## Remarks -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. +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/c6302.md b/docs/code-quality/c6302.md index 23b2679166..e7e9a30709 100644 --- a/docs/code-quality/c6302.md +++ b/docs/code-quality/c6302.md @@ -1,20 +1,17 @@ --- description: "Learn more about: Warning C6302" title: Warning C6302 -ms.date: 09/14/2022 +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 --- # Warning C6302 -> Format string mismatch: character string passed as parameter '*number*' when wide character string is required in call to '*function*' - -This warning indicates that a format string is being passed a narrow character string when a wide character string is specified. +> Format string mismatch. ## Remarks -This issue will likely cause the output to be malformed or for the program to crash at runtime. +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` @@ -30,7 +27,7 @@ void f() } ``` -The following sample code remediates this issue by using `%hs` to specify a single-byte character string: +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 void f() @@ -39,3 +36,9 @@ void f() 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 ac6cbbdea7..bb481fe624 100644 --- a/docs/code-quality/c6303.md +++ b/docs/code-quality/c6303.md @@ -1,20 +1,17 @@ --- description: "Learn more about: Warning C6303" title: Warning C6303 -ms.date: 09/14/2022 +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 --- # Warning C6303 -> Format string mismatch: wide character string passed as parameter '*number*' when character string is required in call to '*function-name*' - -This warning indicates that a format string is being passed a wide character string when a narrow character string is specified. +> Format string mismatch. ## Remarks -This defect is likely to cause a crash or corruption of some form. +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` @@ -32,7 +29,7 @@ void f() } ``` -To correct this warning, use `%ls` (the wide character variant of `%s` 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 @@ -43,3 +40,9 @@ void f() printf_s("%ls", 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)\ +[C6302](./C6302.md) diff --git a/docs/code-quality/c6328.md b/docs/code-quality/c6328.md index 76eb97a120..87bb1426d8 100644 --- a/docs/code-quality/c6328.md +++ b/docs/code-quality/c6328.md @@ -1,41 +1,66 @@ --- description: "Learn more about: Warning C6328" title: Warning C6328 -ms.date: 09/15/2022 +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 --- # Warning C6328 -> Size mismatch: '*type*' passed as parameter '*number*' when '*type*' is required in call to '*function-name*' +> Size mismatch: '*type*' passed as _Param_(*number*) when '*type*' is required in call to '*function-name*' ## Remarks -An argument of type `char` passed 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. This issue could result in a function like `isspace`, which only expects values from 0-255 or `EOF`, being sent a negative value. - -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 such as program fault and termination. +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 -The following code generates this warning. By default, `char` is a signed type in the Microsoft C++ compiler, so the range of values of a `char` is -128 to 127. Therefore, in the following code, `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 + +void f(long long a) +{ + printf("%lld\n", a); // No C6328 emitted. +} +``` + +We can change the type of the expression: ```cpp -void f() +#include + +void f(int a) { - char c = -37; - int retVal = isspace(c); + printf("%d\n", a); // No C6328 emitted. } ``` -The following code remediates this warning by using `static_cast`: +As a last resort when overflow can't happen, we can introduce a cast: ```cpp -void f( ) +#include + +void f(unsigned char a) { - char c = -37; - int retVal = isspace(static_cast(c)); + printf("%hhd\n", static_cast(a)); // No C6328 emitted. } ``` + +## See also + +[C6340](c6340.md) diff --git a/docs/code-quality/c6331.md b/docs/code-quality/c6331.md index 8c3047f9cd..b0e322a1d4 100644 --- a/docs/code-quality/c6331.md +++ b/docs/code-quality/c6331.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Warning 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 --- # Warning C6331 -> Invalid parameter: passing MEM_RELEASE and MEM_DECOMMIT in conjunction to `*function*` 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 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. diff --git a/docs/code-quality/c6335.md b/docs/code-quality/c6335.md index 738a51f131..a5f62fe5fe 100644 --- a/docs/code-quality/c6335.md +++ b/docs/code-quality/c6335.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Warning C6335" title: Warning C6335 +description: "Learn more about: Warning C6335" ms.date: 11/04/2016 f1_keywords: ["C6335", "LEAKING_PROCESS_HANDLE", "__WARNING_LEAKING_PROCESS_HANDLE"] helpviewer_keywords: ["C6335"] -ms.assetid: f81c0859-3d82-4182-8bf1-6c3b76c7486f --- # Warning C6335 @@ -54,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/c6340.md b/docs/code-quality/c6340.md index 90c235edc5..baf564d026 100644 --- a/docs/code-quality/c6340.md +++ b/docs/code-quality/c6340.md @@ -1,11 +1,67 @@ --- description: "Learn more about: Warning C6340" title: Warning C6340 -ms.date: 11/04/2016 -f1_keywords: ["C6340"] +ms.date: 02/14/2024 +f1_keywords: ["C6340", "FORMAT_SIGN_MISMATCH"] helpviewer_keywords: ["C6340"] ms.assetid: c4fe474f-5a27-4148-ba35-1ef021371e13 --- # Warning C6340 -> Mismatch on sign: Incorrect type passed as parameter in call to function +> 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) + + diff --git a/docs/code-quality/c6383.md b/docs/code-quality/c6383.md index 84bf8c2737..72d0ef8b4f 100644 --- a/docs/code-quality/c6383.md +++ b/docs/code-quality/c6383.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Warning 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 --- # Warning C6383 -> 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*` +> 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 instead required. diff --git a/docs/code-quality/c6386.md b/docs/code-quality/c6386.md index 2419833b70..7aa56f9f9f 100644 --- a/docs/code-quality/c6386.md +++ b/docs/code-quality/c6386.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Warning C6386" title: Warning C6386 -ms.date: 11/04/2016 +ms.date: 4/30/2025 f1_keywords: ["C6386", "WRITE_OVERRUN", "__WARNING_WRITE_OVERRUN"] helpviewer_keywords: ["C6386"] -ms.assetid: 84e69fe8-8f03-4bb3-b194-e5551882e214 --- # Warning C6386 @@ -23,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 @@ -39,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 d96f377b6d..a925d0b397 100644 --- a/docs/code-quality/c6387.md +++ b/docs/code-quality/c6387.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Warning C6387" title: Warning C6387 +description: "Learn more about: Warning C6387" ms.date: 11/04/2016 f1_keywords: ["C6387", "INVALID_PARAM_VALUE_1", "__WARNING_INVALID_PARAM_VALUE_1"] helpviewer_keywords: ["C6387"] -ms.assetid: 3ea2fc4d-ffc3-4c3c-bfae-d42aa56235d8 --- # Warning C6387 @@ -27,7 +26,7 @@ _Post_ _Null_ char * g(); void f(_In_ char *pch); -void main() +int main() { char *pCh = g(); f(pCh); // Warning C6387 @@ -43,7 +42,7 @@ _Post_ _Notnull_ char * g(); void f(_In_ char *pch); -void main() +int main() { char *pCh = g(); f(pCh); 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/c6411.md b/docs/code-quality/c6411.md index a24d5c9118..a4a99565a8 100644 --- a/docs/code-quality/c6411.md +++ b/docs/code-quality/c6411.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Warning C6411" title: Warning C6411 +description: "Learn more about: Warning C6411" ms.date: 11/04/2016 f1_keywords: ["C6411", "POTENTIAL_READ_OVERRUN"] -ms.assetid: 6bbc1734-eec4-4ad6-9908-4ed2a5f025db +helpviewer_keywords: ["C6411"] --- # Warning C6411 diff --git a/docs/code-quality/c6412.md b/docs/code-quality/c6412.md index 5c29356882..230011ec6e 100644 --- a/docs/code-quality/c6412.md +++ b/docs/code-quality/c6412.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Warning C6412" title: Warning C6412 +description: "Learn more about: Warning C6412" ms.date: 11/04/2016 f1_keywords: ["C6412", "POTENTIAL_WRITE_OVERRUN"] -ms.assetid: 6498f045-1bdc-4428-9d95-d9498de207bb +helpviewer_keywords: ["C6412"] --- # Warning C6412 diff --git a/docs/code-quality/c6506.md b/docs/code-quality/c6506.md index df143e3c84..377aef7813 100644 --- a/docs/code-quality/c6506.md +++ b/docs/code-quality/c6506.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Warning C6506" title: Warning C6506 +description: "Learn more about: Warning C6506" ms.date: 11/04/2016 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 --- # Warning C6506 @@ -21,7 +20,7 @@ Code analysis name: `BUFFER_SIZE_ON_NON_POINTER_OR_ARRAY` The following code generates this warning: ```cpp -#include +#include void f(_Out_ char c) { c = 'd'; @@ -31,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/c6701.md b/docs/code-quality/c6701.md index bdbbdf6afa..386d29a099 100644 --- a/docs/code-quality/c6701.md +++ b/docs/code-quality/c6701.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Warning C6701" title: Warning C6701 +description: "Learn more about: Warning C6701" ms.date: 11/04/2016 f1_keywords: ["C6701"] -helpviewer_keywords: ["C67901"] -ms.assetid: c48484e2-542c-4f7b-93ea-98c6367cb3d9 +helpviewer_keywords: ["C6701"] --- # Warning C6701 diff --git a/docs/code-quality/c6993.md b/docs/code-quality/c6993.md index e4df96bfab..54f78c56c9 100644 --- a/docs/code-quality/c6993.md +++ b/docs/code-quality/c6993.md @@ -1,12 +1,14 @@ --- -description: "Learn more about: Warning C6993" title: Warning C6993 -ms.date: 11/04/2016 +description: "Learn more about: Warning C6993" +ms.date: 2/25/2025 f1_keywords: ["C6993"] -ms.assetid: 7ea93bc6-b934-4b6b-b71a-a56e765fb4cd +helpviewer_keywords: ["C6993"] --- # Warning C6993 > Code analysis ignores OpenMP constructs; analyzing single-threaded code -This warning indicates that the Code Analyzer has encountered Open MP pragmas that it can't 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 6e5736bd79..4ca022014e 100644 --- a/docs/code-quality/c6995.md +++ b/docs/code-quality/c6995.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Warning C6995" title: Warning C6995 +description: "Learn more about: Warning C6995" ms.date: 11/04/2016 f1_keywords: ["C6995"] -ms.assetid: 1e82e3ad-99fe-4a35-87d5-359c74b9658e +helpviewer_keywords: ["C6995"] --- # Warning C6995 diff --git a/docs/code-quality/c6997.md b/docs/code-quality/c6997.md index 4090bea051..8cbfc9bd5e 100644 --- a/docs/code-quality/c6997.md +++ b/docs/code-quality/c6997.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Warning C6997" title: Warning C6997 +description: "Learn more about: Warning C6997" ms.date: 11/04/2016 f1_keywords: ["C6997", "IGNORED_ANNOTATIONS"] -ms.assetid: 48fd86a3-d57b-4ecb-979a-5d3a4186482e +helpviewer_keywords: ["C6997"] --- # Warning C6997 diff --git a/docs/code-quality/clang-tidy.md b/docs/code-quality/clang-tidy.md index 004a9c4e97..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/22/2022 +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 or later. 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 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/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 68220286ec..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,7 +10,7 @@ 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 )` @@ -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 b54c5ce1d3..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 @@ -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 c60c532241..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,7 +41,7 @@ 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: @@ -140,6 +142,8 @@ items: href: ../code-quality/c26456.md - name: Warning C26457 href: ../code-quality/c26457.md + - name: Warning C26459 + href: ../code-quality/c26459.md - name: Warning C26460 href: ../code-quality/c26460.md - name: Warning C26461 @@ -170,6 +174,8 @@ items: href: ../code-quality/c26477.md - name: Warning C26478 href: ../code-quality/c26478.md + - name: Warning C26479 + href: ../code-quality/c26479.md - name: Warning C26481 href: ../code-quality/c26481.md - name: Warning C26482 @@ -255,6 +261,8 @@ items: href: ../code-quality/c6014.md - name: Warning C6029 href: ../code-quality/c6029.md + - name: Warning C6030 + href: ../code-quality/c6030.md - name: Warning C6031 href: ../code-quality/c6031.md - name: Warning C6053 @@ -267,6 +275,8 @@ items: href: ../code-quality/c6063.md - name: Warning C6064 href: ../code-quality/c6064.md + - name: Warning C6065 + href: ../code-quality/c6065.md - name: Warning C6066 href: ../code-quality/c6066.md - name: Warning C6067 @@ -473,6 +483,20 @@ items: href: ../code-quality/c6389.md - 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: Warning C6401 @@ -567,6 +591,10 @@ items: href: ../code-quality/c26117.md - name: Warning C26130 href: ../code-quality/c26130.md + - name: Warning C26132 + href: c26132.md + - name: Warning C26133 + href: c26133.md - name: Warning C26135 href: ../code-quality/c26135.md - name: Warning C26138 @@ -607,10 +635,32 @@ items: 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: Warning C28021 diff --git a/docs/code-quality/understanding-sal.md b/docs/code-quality/understanding-sal.md index 8669d1689b..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 @@ -94,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 @@ -145,7 +144,7 @@ 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 @@ -172,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 @@ -198,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 @@ -225,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 @@ -256,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 @@ -285,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 @@ -315,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 @@ -347,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\_ @@ -366,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 @@ -384,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. @@ -392,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-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/align-cpp.md b/docs/cpp/align-cpp.md index 3f3a3411d6..480640779f 100644 --- a/docs/cpp/align-cpp.md +++ b/docs/cpp/align-cpp.md @@ -7,7 +7,7 @@ helpviewer_keywords: ["align __declspec keyword", "__declspec keyword [C++], ali --- # `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** @@ -19,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. 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 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. @@ -27,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). 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/arrays-cpp.md b/docs/cpp/arrays-cpp.md index 79ca884956..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 @@ -121,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. @@ -162,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: @@ -357,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 3440de323d..b34a559f80 100644 --- a/docs/cpp/attributes.md +++ b/docs/cpp/attributes.md @@ -3,8 +3,9 @@ description: "Learn more about: Attributes in C++" title: "Attributes in C++" 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: 12/06/2022 +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. @@ -31,22 +32,26 @@ 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. -### `[[noreturn]]` - -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. - ### `[[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 non-static 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). +**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. +### `[[likely]]` + +**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. + +### `[[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.) 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: @@ -62,13 +67,9 @@ int main() } ``` -### `[[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.) The `[[maybe_unused]]` attribute specifies that a variable, function, class, typedef, non-static 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. - -### `[[likely]]` +### `[[noreturn]]` -**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. +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]]` @@ -76,16 +77,18 @@ int main() ## Microsoft-specific attributes -### `[[gsl::suppress(rules)]]` +### `[[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(rules)]]` 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: +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)]] // This attribute suppresses Bounds rule #1 + [[gsl::suppress("bounds.1", justification: "This attribute suppresses Bounds rule #1")]] { int* q = p + 1; // GSL warning C26481 suppressed p = q--; // GSL warning C26481 suppressed @@ -101,17 +104,46 @@ The example raises these warnings: - [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. +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]] + { + 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 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. +The `[[msvc::intrinsic]]` attribute has three constraints on the function it's applied to: -The `[[msvc::intrinsic]]` attribute has two 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.) -1. The function can't be recursive; its body must only have a return statement with a cast. -1. The function can only accept a single parameter. -1. 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 @@ -127,6 +159,14 @@ void f() { } ``` +### `[[msvc::noinline]]` + +When placed before a function declaration, the Microsoft-specific attribute `[[msvc::noinline]]` has the same meaning as `__declspec(noinline)`. + +### `[[msvc::noinline_calls]]` + +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. + ### `[[msvc::no_tls_guard]]` 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/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/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 d148fa4bae..5e759dc2e9 100644 --- a/docs/cpp/bitwise-inclusive-or-operator-pipe.md +++ b/docs/cpp/bitwise-inclusive-or-operator-pipe.md @@ -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/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 54f6191224..3d97b74bea 100644 --- a/docs/cpp/class-member-overview.md +++ b/docs/cpp/class-member-overview.md @@ -17,7 +17,7 @@ The full list of member categories is as follows: - [Overview of member functions](overview-of-member-functions.md). -- [Mutable](static-members-cpp.md) and [static](static-members-cpp.md) data members, 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 diff --git a/docs/cpp/class-templates.md b/docs/cpp/class-templates.md index 9799e84fc0..42bb8d2539 100644 --- a/docs/cpp/class-templates.md +++ b/docs/cpp/class-templates.md @@ -83,7 +83,6 @@ using namespace std; class X { - template struct Y { 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/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-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 1f1fbde94a..fc2837dbf0 100644 --- a/docs/cpp/const-cpp.md +++ b/docs/cpp/const-cpp.md @@ -147,7 +147,7 @@ int main() ## 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: ```C const int i = 2; @@ -159,13 +159,18 @@ You can then use this variable in another module as follows: 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: -If you wish to declare an **`extern`** variable in a C++ source code file for use in a C source code file, use: +```cpp +extern const int i; +``` + +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; 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/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/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/declspec.md b/docs/cpp/declspec.md index 253de9e94d..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/01/2022 +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 aren't 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 @@ -30,6 +30,7 @@ The extended attribute syntax for specifying storage-class information uses the  **`dllimport`**\  **`dllexport`**\  **`empty_bases`**\ + **`hybrid_patchable`**\  **`jitintrinsic`**\  **`naked`**\  **`noalias`**\ @@ -49,7 +50,7 @@ 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), [`empty_bases`](../cpp/empty-bases.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`**, **`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. @@ -94,5 +95,5 @@ __declspec( thread ) int tls_i = 1; ## See also -[Keywords](../cpp/keywords-cpp.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 560e1a162e..2b387820ce 100644 --- a/docs/cpp/decltype-cpp.md +++ b/docs/cpp/decltype-cpp.md @@ -1,10 +1,9 @@ --- description: "Learn more about: decltype (C++)" title: "decltype (C++)" -ms.date: 09/27/2022 +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++) @@ -40,7 +39,7 @@ The following code example demonstrates some uses of the **`decltype`** type spe ```cpp int var; const int&& fx(); -struct A { double x; } +struct A { double x; }; const A* a = new A(); ``` 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 be9b5b3b3b..e19dca7628 100644 --- a/docs/cpp/dllexport-dllimport.md +++ b/docs/cpp/dllexport-dllimport.md @@ -23,7 +23,7 @@ These attributes explicitly define the DLL's interface to its client, which can 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, 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"` include platform-specific decoration that's based on the calling convention. No name decoration is applied to exported C functions or C++ `extern "C"` functions that use the **`__cdecl`** calling convention. For more information on name decoration in C/C++ code, see [Decorated names](../build/reference/decorated-names.md). +**`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. 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/enumerations-cpp.md b/docs/cpp/enumerations-cpp.md index ff81800757..bce6d27a4e 100644 --- a/docs/cpp/enumerations-cpp.md +++ b/docs/cpp/enumerations-cpp.md @@ -137,7 +137,7 @@ 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 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 can't be implicitly converted, as shown in the following example: 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 8fa4a3da27..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). - +- 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/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/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/friend-cpp.md b/docs/cpp/friend-cpp.md index a2364c59d3..4e4aa5f1d0 100644 --- a/docs/cpp/friend-cpp.md +++ b/docs/cpp/friend-cpp.md @@ -4,11 +4,10 @@ title: "friend (C++)" 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++) -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 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 @@ -225,8 +224,9 @@ Friendship isn't inherited, meaning that classes derived from `YourOtherClass` c 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 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 2d13256630..8f8c24a61a 100644 --- a/docs/cpp/function-overloading.md +++ b/docs/cpp/function-overloading.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: Function Overloading" title: "Function Overloading" -ms.date: 06/10/2022 +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++ 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, 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. +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 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. @@ -270,9 +269,9 @@ 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")\ +:::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,7 +282,7 @@ 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)\ +:::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. @@ -308,7 +307,7 @@ public: void Print( int i ) { -}; +} UDC udc; @@ -402,7 +401,6 @@ using namespace std; class C { - public: C() {/*expensive initialization*/} vector get_data() & diff --git a/docs/cpp/functions-cpp.md b/docs/cpp/functions-cpp.md index 92f56686bd..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){...} @@ -199,7 +192,7 @@ A function declared with the single keyword **`void`** in the parameter declarat 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 @@ -232,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 @@ -242,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) @@ -264,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. @@ -351,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 @@ -397,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/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 349708fa55..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: 02/14/2022 +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; @@ -40,11 +40,9 @@ namespace ModuleA_NS } ``` -Non-exported names aren't 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() { @@ -64,9 +62,8 @@ Use an **`import`** declaration to make a module's names visible in your program module ModuleA; #include "custom-lib.h" -import std.core; -import std.regex; -import ModuleB; +import std; +import myModule; // begin declarations here: template @@ -114,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 99eefb75a3..4ba7817947 100644 --- a/docs/cpp/index.yml +++ b/docs/cpp/index.yml @@ -1,5 +1,5 @@ ### YamlMime:Landing -title: C++ language documentation +title: C++ documentation summary: Learn to use C++ and the C++ standard library. metadata: @@ -7,6 +7,7 @@ metadata: description: C++ programming reference for users of Microsoft C++ and Visual Studio. ms.topic: landing-page 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 @@ -76,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/inline-functions-cpp.md b/docs/cpp/inline-functions-cpp.md index 00712e25a4..edfd41def2 100644 --- a/docs/cpp/inline-functions-cpp.md +++ b/docs/cpp/inline-functions-cpp.md @@ -1,69 +1,72 @@ --- title: "Inline Functions (C++)" description: "The C++ inline keyword can be used to suggest inline functions to the compiler." -ms.date: 08/24/2022 +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++) -The **`inline`** keyword tells the compiler to substitute the code within the function definition for every instance of a function call. +The **`inline`** keyword suggests that the compiler substitute the code within the function definition in place of each call to that function. -Using inline functions can make your program faster because they eliminate the overhead associated with function calls. The compiler can optimize functions expanded inline in ways that aren't available to normal functions. +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 occurs 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. +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, you can't 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). @@ -71,20 +74,18 @@ The compiler treats the inline expansion options and keywords as suggestions. Th 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 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. 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. 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. -The [`/Ob`](../build/reference/ob-inline-function-expansion.md) compiler optimization option helps to determine whether inline function expansion actually occurs. - +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 @@ -92,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; } ``` @@ -107,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; }; ``` @@ -121,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. @@ -152,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; @@ -179,85 +173,102 @@ 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: - -- 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. +A macro has some things in common with an `inline` function. But there are important differences. Consider the following example: -- 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 -inline char toupper( char a ) { - return ((a >= 'a' && a <= 'z') ? a-('a'-'A') : a ); +#define sqr(a) ((a) * (a)) + +int increment(int& number) +{ + return number++; } -int main() { - printf_s("Enter a character: "); - char ch = toupper( getc(stdin) ); - printf_s( "%c", ch ); +inline int square(int a) +{ + return a * a; +} + +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)\ 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 527f09eaa9..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.) @@ -104,7 +105,7 @@ 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. 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 8533e8f8b1..b5a178d585 100644 --- a/docs/cpp/logical-or-operator-pipe-pipe.md +++ b/docs/cpp/logical-or-operator-pipe-pipe.md @@ -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 9e632f6251..ac291e1374 100644 --- a/docs/cpp/main-function-command-line-args.md +++ b/docs/cpp/main-function-command-line-args.md @@ -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/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 d928f8fa72..309913a75b 100644 --- a/docs/cpp/modules-cpp.md +++ b/docs/cpp/modules-cpp.md @@ -1,53 +1,28 @@ --- title: "Overview of modules in C++" -ms.date: 03/30/2022 -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 that turns C++ libraries and programs into components. 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 reduce many of the problems associated with the use of header files. They often reduce compilation times. Macros, preprocessor directives, and non-exported 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. - -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 rather than include it textually by using `#include` in the preprocessor. We recommend 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. - -To contrast modules with other ways to import the standard library, see [Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md). - -## Enable modules in the Microsoft C++ compiler - -As of Visual Studio 2022 version 17.1, C++20 standard modules are fully implemented in the Microsoft C++ compiler. - -Before it was specified by the C++20 standard, Microsoft had experimental support for modules in the Microsoft C++ compiler. The compiler also supported importing the Standard Library as modules, described below. - -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. This section describes the older, experimental method, which is still supported. For information about the new standardized way to import the Standard Library using modules, see [Import the C++ standard library using modules](tutorial-import-stl-named-module.md). - -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 Standard Library modules, compile with [`/experimental:module`](../build/reference/experimental-module.md) and [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md). 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)**. - -A module and the code that consumes it must be compiled with the same compiler options. +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. -## Consume C++ Standard Library as 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. -This section describes the experimental implementation, which is still supported. The new standardized way of consuming the C++ Standard Library as modules is described in [Import the C++ standard library using modules](tutorial-import-stl-named-module.md). +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. -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 experimental library is split into 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 contrast modules with other ways to import the standard library, see [Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md). -To consume these modules, add an import declaration to the top of the source code file. For example: +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). -```cpp -import std.core; -import std.regex; -``` +## Single-partition modules -To consume the Microsoft Standard Library modules, 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 *`Example.ixx`*. The *`.ixx`* extension is required for module interface files in Visual Studio. In this example, the interface file contains both the function definition and the declaration. However, you can also place the definitions in one or more separate module implementation files, as shown in a later example. The `export module Example;` statement indicates that this file is the primary interface for a module called `Example`. The **`export`** modifier on `f()` indicates that this function is visible when `Example` is imported by another program or module. The module references a namespace `Example_NS`. +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 // Example.ixx @@ -57,22 +32,24 @@ export module Example; 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 `Example`. The name `Example_NS` is visible here, but not all of its members. Also, the macro `ANSWER` isn't 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 // MyProgram.cpp +import std; import Example; -import std.core; using namespace std; @@ -84,7 +61,7 @@ int main() } ``` -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 @@ -109,64 +86,69 @@ The `import` declaration can appear only at global scope. ## Implementing modules -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 consist of a single file that combines the module interface and implementation. You can also put the implementations in one or more separate module implementation files, similar to how *`.h`* and *`.cpp`* files are used. +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 a module partition name. A partition may also have one or more partition implementation files. The module as a whole has one *primary module interface*, the public interface of the module that may also import and export the partition interfaces. +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. 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* is a module unit that exports a module name or module partition name. A module interface unit has `export module` in its module declaration. - -- A *module implementation unit* is a module unit that doesn't export a module name or module partition name. As the name implies, it's used to implement a module. +- 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. -- A *primary module interface unit* is a module interface unit that exports the module name. There must be one and only one primary module interface unit in a module. - -- A *module partition interface unit* is a module interface unit that exports a module partition name. - -- A *module partition implementation unit* is a module implementation unit that has a module partition name in its module declaration, but no `export` keyword. - -The **`export`** keyword is used in interface files only. An implementation file can **`import`** another module, but can't **`export`** any names. Implementation files can have any extension. +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 it does argument-dependent lookup for overload resolutions in the importing translation unit, the compiler considers functions 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 -A module partition is similar to a module, except it shares ownership of all declarations in the entire module. All names 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, and so on) in one partition and define it in another. A partition implementation file begins like this: +A module partition is similar to a module, except: + +- 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 Example:part1; ``` -The partition interface file begins like this: +A partition interface file begins like this: ```cpp 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 Example:part2; import :part1; ``` -The primary interface unit must import and re-export all of 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; -... ``` 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 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 @@ -174,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 @@ -184,9 +166,10 @@ 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 ``` @@ -201,6 +184,7 @@ import "myheader.h"; ## See also +[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) \ No newline at end of file +[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/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/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/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/overload-resolution-of-function-template-calls.md b/docs/cpp/overload-resolution-of-function-template-calls.md index 17455439ed..f8e8fc3031 100644 --- a/docs/cpp/overload-resolution-of-function-template-calls.md +++ b/docs/cpp/overload-resolution-of-function-template-calls.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Overload resolution of function template calls" 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 @@ -26,7 +25,7 @@ template void f(T1, T2) { cout << "void f(T1, T2)" << endl; -}; +} int main() { @@ -58,7 +57,7 @@ template void f(T1, T2) { cout << "void f(T1, T2)" << endl; -}; +} int main() { 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 85a25f8016..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; ``` 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 7e4df62435..c12c7051c6 100644 --- a/docs/cpp/raw-pointers.md +++ b/docs/cpp/raw-pointers.md @@ -81,7 +81,6 @@ void func_B(MyClass mc) mc.print(); // "Erika, 21" } - int main() { // Use the * operator to declare a pointer type @@ -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]); @@ -170,7 +168,6 @@ using namespace std; int main() { - BITMAPINFOHEADER header; header.biHeight = 100; // Multiple of 4 for simplicity. header.biWidth = 100; @@ -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/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/scope-resolution-operator.md b/docs/cpp/scope-resolution-operator.md index 7d23071451..02a1ee72fa 100644 --- a/docs/cpp/scope-resolution-operator.md +++ b/docs/cpp/scope-resolution-operator.md @@ -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/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/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/string-and-character-literals-cpp.md b/docs/cpp/string-and-character-literals-cpp.md index 70addb2b9b..643fd31dae 100644 --- a/docs/cpp/string-and-character-literals-cpp.md +++ b/docs/cpp/string-and-character-literals-cpp.md @@ -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. -In versions of Visual Studio before Visual Studio 2022 version 17.0, the maximum length of a string literal is 65,535 bytes. This limit applies to both narrow string literals and wide string literals. In Visual Studio 2022 version 17.0 and later, this restriction is lifted and string length is limited by available resources. +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 diff --git a/docs/cpp/structured-exception-handling-c-cpp.md b/docs/cpp/structured-exception-handling-c-cpp.md index e73c9c0d9d..ab3f3c5817 100644 --- a/docs/cpp/structured-exception-handling-c-cpp.md +++ b/docs/cpp/structured-exception-handling-c-cpp.md @@ -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/this-pointer.md b/docs/cpp/this-pointer.md index ef9e1bb859..1b560dd372 100644 --- a/docs/cpp/this-pointer.md +++ b/docs/cpp/this-pointer.md @@ -1,10 +1,9 @@ --- 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] --- # The `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 @@ -133,41 +132,22 @@ your buffer ## 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: - -```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() -{ -} -``` +[*`cv-qualifier-list`*] *`class-type`* **`* const this`** -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 @@ -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 bc6350835c..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 @@ -694,6 +696,8 @@ items: 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 97554f6894..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 index 7b1c9deed7..b2c961353f 100644 --- a/docs/cpp/tutorial-import-stl-named-module.md +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -1,15 +1,16 @@ --- -title: "Tutorial: Import the standard library (STL) using modules (C++)" -ms.date: 12/02/2022 +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 +description: Learn how to import the C++ standard library (STL) using modules from the command line --- -# Tutorial: Import the C++ standard library using modules -Learn how to import the C++ standard library using C++ library modules. This is significantly faster to compile and more robust than using header files or header units or precompiled headers (PCH). +# 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: @@ -21,59 +22,54 @@ In this tutorial, learn about: This tutorial requires Visual Studio 2022 17.5 or later. -> [!WARNING] -> This tutorial is for a preview feature. The feature is subject to change between preview releases. You shouldn't use preview features in production code. - -## An introduction to the standard library modules +## Introduction to standard library modules -Header files suffer from semantics that change depending on macro definitions, semantics that change depending on the order you include them, and they slow compilation. Modules solve these problems. +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 significantly faster and more robust than including header files or header units or precompiled headers (PCH). +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`. +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 that are in namespace `std` such as `std::vector` and `std::sort`. It also exports the contents of C wrapper headers such as ``, ``, `` that provide `std::byte`, `std::printf()`, and so on. The C functions defined in the *global namespace* such as `::printf()` and `::fopen` aren't exported. This improves the situation where previously including a C wrapper header like `` which provides `std::` qualified versions of the C runtime functions *also* included the actual C header, like `stdio.h`, which meant the C global namespace versions were also brought in. This is no longer a problem if you import `std`. -- `std.compat` exports everything in `std`, and adds the global namespace counterparts of the C runtime such as `::printf`, `::fopen`, `::size_t`, `::strlen`, and so on. This module makes it easier when working with a codebase that refers to many C runtime functions/types in the global namespace. +- `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. That is, it's faster to bring in the entire standard library with `import std;` (or `import std.compat`) than it's to `#include `, for example. +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. -## A little about C++ modules +## About C++ modules -Header files are how declarations and definitions have been shared between source files in C++. Prior to 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 or aren't defined. They also slow compilation because they have to be reprocessed by every source file that includes them. +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 for the standard library. +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 significantly faster than it can process `#include` files, and uses less memory at compile time as well. Macro definitions defined in a named module aren't exposed, nor are private implementation details. - -For in depth information about modules, see [Overview of modules in C++](modules-cpp.md) That article also discusses consuming the C++ standard library as modules, but uses an older and experimental way of doing it. +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 demonstrates how to consume the standard library as a module using the command line compiler. The Visual Studio IDE experience for importing the standard library as a module is still being implemented. +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 standard library is imported into your application with the statement `import std;` or `import std.compat;`. But first, you must compile the standard library named modules. The following steps demonstrate how. +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: `std` +### 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 preview version 17.5 or above. You'll get errors if you use the wrong version of the prompt. The examples used in this tutorial are for the CMD shell. If you use PowerShell, substitute `"$Env:VCToolsInstallDir\modules\std.ixx"` for `"%VCToolsInstallDir\modules\std.ixx"`. -1. Create a directory such as `C:\STLModules`, and make it the current directory. +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: - ```dos - cl /std:c++latest /EHsc /nologo /W4 /MTd /c "%VCToolsInstallDir%\modules\std.ixx" + ```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. If you're still having issues, please file a bug at [Visual Studio Developer Community](https://developercommunity.visualstudio.com/home). + If you get errors, ensure that you're using the correct version of the command prompt. - You should compile the `std` named module using the same compiler settings that you intend to use with the code that imports it. 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. + 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 compiler command above, the compiler outputs two files: + 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 so that functionality you use from the standard library can be statically linked into 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: @@ -81,10 +77,14 @@ The standard library is imported into your application with the statement `impor |---|---| | [`/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"`. | - | [`/MTd`](../build/reference/md-mt-ld-use-run-time-library.md) | Use the static multithreaded debug run-time library. | - | [`/c`](../build/reference/c-compile-without-linking.md) | Compile without linking. | + | [`/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. To try out importing the `std` library, start by creating a file named `importExample.cpp` with the following content: +1. Import the `std` library you built by first creating a file named `importExample.cpp` with the following content: ```cpp // requires /std:c++latest @@ -102,20 +102,25 @@ The standard library is imported into your application with the statement `impor } ``` - In the preceding code, `import std;` replaces `#include ` and `#include `. The statement `import std;` makes all of the standard library available with one statement. If you're concerned about performance, it may help to know that importing the entire standard library is often significantly faster than processing a single standard library header file such as `#include `. + 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: - ```dos - cl /std:c++latest /EHsc /nologo /W4 /MTd importExample.cpp std.obj + ```cmd + cl /c /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp + link importExample.obj std.obj ``` - We didn't have to specify `std.ifc` on the command line because the compiler automatically looks for the `.ifc` file that matches the module name specified by an `import` statement. When the compiler encounters `import std;`, it finds `std.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, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. + 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. - 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. Make sure to put it before any `.cpp` files that consume it. By default, the output executable's name is taken from the first input file. Use the `/Fe` compiler option to specify the output 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: + 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. - ```dos - cl /FeimportExample /std:c++latest /EHsc /nologo /W4 /MTd "%VCToolsInstallDir%\modules\std.ixx" importExample.cpp + 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: @@ -125,37 +130,39 @@ The standard library is imported into your application with the statement `impor 555 ``` - The key command-line switches in this example are the same as the previous example, except that the `/c` switch isn't used. - ## 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`, `::fopoen`, `::size_t`, and so on. +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 (that is, 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 name mentions 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()`. You'll know that you should consider using `import std.compat;` if you see an error like `error C3861: 'printf': identifier not found` when you try to compile your code. +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: `std.compat` +### Example: How to build and import `std.compat` -Before you can use `import std.compat;` in your code, you must compile the named module `std.compat.ixx`. The steps are similar to for building the `std` named module. The steps include building the `std` named module first because `std.compat` depends on it: +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 preview version 17.5 or above. If you use the wrong version of the prompt, you'll get compiler errors. -1. Create a directory to try this example, such as `C:\STLCompatModules`, and make it the current directory. +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: - ```dos - cl /std:c++latest /EHsc /nologo /W4 /MTd /c "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" + ```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 imports 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. + 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. If you're still having issues, please file a bug at [Visual Studio Developer Community](https://developercommunity.visualstudio.com/home). While this feature is still in preview, you can find a list of known problems under [Standard library header units and modules tracking issue 1694](https://github.com/microsoft/stl/issues/1694). + 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 as well when you compile the sample app so that the functionality you use from the standard library can be statically linked into 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. To try out importing the `std.compat` library, create a file named `stdCompatExample.cpp` with the following content: +1. Import the `std.compat` library by first creating a file named `stdCompatExample.cpp` with the following content: ```cpp import std.compat; @@ -172,27 +179,29 @@ Before you can use `import std.compat;` in your code, you must compile the named } ``` - 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. If you're concerned about performance, the performance of modules is such that importing this named module, which includes the C++ standard library and C runtime library global namespace functions, is faster than even processing a single include like `#include `. + 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: - ```dos - cl /std:c++latest /EHsc /nologo /W4 /MTd stdCompatExample.cpp std.obj std.compat.obj + ```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, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. + 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. - Even though we're importing `std.compat`, you must also link against `std.obj` because that is where the standard library implementation lives that `std.compat` builds upon. + 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 step of building the `std` and `std.compat` standard library named modules with the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` and `"%VCToolsInstallDir%\modules\std.compat.ixx"` (in that order) to the command line. 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: + 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: - ```dos - cl /FestdCompatExample /std:c++latest /EHsc /nologo /W4 /MTd "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" stdCompatExample.cpp + ```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 ``` - I've shown them as separate steps in this tutorial 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 it may be convenient to build them all at once. + 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 compiler command above produces an executable named `stdCompatExample.exe`. When you run it, it produces the following output: + 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() @@ -201,13 +210,13 @@ Before you can use `import std.compat;` in your code, you must compile the named ## Standard library named module considerations -Versioning for named modules is the same as for headers. The `.ixx` named module files live alongside the headers, for example: `"%VCToolsInstallDir%\modules\std.ixx`, which resolves to `C:\Program Files\Microsoft Visual Studio\2022\Preview\VC\Tools\MSVC\14.35.32019\modules\std.ixx` in the version of the tools used at the time of this writing. Select the version of the named module to use the same way you choose the version of the header file to use--by the directory you refer to them from. +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 named modules. 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, ``. +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: no header guard `#ifndef` required. The compiler knows when it has already imported a named module and ignores duplicate attempts to do so. +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 `. @@ -224,4 +233,4 @@ In this tutorial, you've imported the standard library using modules. Next, lear [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) \ No newline at end of file +[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 dc0b11bbc7..776ac6f114 100644 --- a/docs/cpp/tutorial-named-modules-cpp.md +++ b/docs/cpp/tutorial-named-modules-cpp.md @@ -1,6 +1,6 @@ --- title: "Named modules tutorial in C++" -ms.date: 08/08/2022 +ms.date: 02/13/2025 ms.topic: "tutorial" author: "tylermsft" ms.author: "twhitney" @@ -9,7 +9,7 @@ description: Named modules in C++20 provide a modern alternative to header files --- # Named modules tutorial (C++) -This tutorial is about creating C++20 modules. Modules replace header files. You'll learn how modules are an improvement on header files. +This tutorial is about creating C++20 modules. Modules are a significant improvement on header files. In this tutorial, learn how to: @@ -22,13 +22,11 @@ In this tutorial, learn how to: This tutorial requires 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). - ## 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. They 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. +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 a modern approach to componentizing C++ programs: *modules*. +C++20 introduces *modules* as a modern approach to componentizing C++ programs. 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. @@ -50,7 +48,7 @@ Your code can consume modules in the same project, or any referenced projects, a ## Create the project -As we build a simple project, we'll look at various aspects of modules. The project will 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. 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. @@ -62,11 +60,11 @@ Because modules are a C++20 feature, use the [`/std:c++20` or `/std:c++latest`]( ## Create the primary module interface unit -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 will see. There can only be one primary module interface unit per module. +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. 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 choose **Add**. @@ -88,27 +86,27 @@ Replace the contents of *`BasicPlane.Figures.ixx`* file with: 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 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, 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 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. 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`. +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` API. The other part will be `Rectangle`. Imagine that this API will grow into something more complex. 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. For reasons of logical organization, and potential build efficiency, we want to make this part of the API easily understandable on its own. To do so, 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. Module partitions are useful for dividing the module implementation into 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. 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 choose **Add**. -Because it's a module partition file, we've added 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. +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 *`BasicPlane.Figures-Point.ixx`* with: @@ -123,13 +121,13 @@ export struct Point 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, 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. +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, 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: 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 *`BasicPlane.Figures-Rectangle.ixx`* with: @@ -156,13 +154,13 @@ Next, `import :Point;` shows how to import a module partition. The `import` stat 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. 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 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 will be visible to other files that are part of the module, but not to importers of the module. +- 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. @@ -179,11 +177,11 @@ 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 ``` -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 are importing a module partition. +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. 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 next by creating a module implementation file. +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 @@ -219,7 +217,7 @@ Anything you declare within an implementation unit is only visible to the module ## 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 @@ -237,7 +235,7 @@ int main() } ``` -The statement `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 any `#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: @@ -252,7 +250,7 @@ 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, the exported module interface unit 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 so, set the **Compile As** property in the **Advanced** tab for the source file's properties page to **Compile As Module (/interface)**: @@ -265,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 @@ -300,12 +298,13 @@ For a more in-depth look at module syntax, see [Modules](modules-cpp.md). 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 into smaller pieces, which can result in faster build times. This technique 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: ```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 @@ -315,7 +314,7 @@ module [module-name]; // required. Identifies which named module this implementa ### 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. @@ -358,7 +357,7 @@ A module and the code that imports it must be compiled with the same compiler op - 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 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 make it easier to use 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. 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. @@ -372,7 +371,7 @@ Module partitions make it easier to logically factor a large module. They can be ## Summary -In this tutorial, you've been introduced to the basics of C++20 modules. You've created a primary module interface, defined a module partition, and built a module implementation file. +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 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/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 487f7c2c53..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 @@ -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/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/welcome-back-to-cpp-modern-cpp.md b/docs/cpp/welcome-back-to-cpp-modern-cpp.md index 9588b53975..dd8346fd6d 100644 --- a/docs/cpp/welcome-back-to-cpp-modern-cpp.md +++ b/docs/cpp/welcome-back-to-cpp-modern-cpp.md @@ -3,7 +3,6 @@ title: "Welcome back to C++ - Modern C++" description: "Describes the new programming idioms in Modern C++ and their rationale." ms.date: 06/02/2022 ms.topic: "conceptual" -ms.assetid: 1cb1b849-ed9c-4721-a972-fd8f3dab42e2 --- # Welcome back to C++ - Modern C++ @@ -64,10 +63,7 @@ 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). @@ -79,11 +75,8 @@ Before you assume that you need to write a custom algorithm for your program, fi 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. 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/casting-c-cx.md b/docs/cppcx/casting-c-cx.md index 4eb0302f84..621c4ab35d 100644 --- a/docs/cppcx/casting-c-cx.md +++ b/docs/cppcx/casting-c-cx.md @@ -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/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 af0f96e6d6..3ea53942eb 100644 --- a/docs/cppcx/delegates-c-cx.md +++ b/docs/cppcx/delegates-c-cx.md @@ -18,7 +18,7 @@ Delegates are most commonly used in conjunction with events. An event has a dele 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 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/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/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-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 fca0453596..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,83 +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 @@ -155,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 @@ -174,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 @@ -233,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 @@ -252,20 +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; @@ -273,42 +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 @@ -319,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( @@ -391,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-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 eb270ad593..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: @@ -173,6 +172,6 @@ public: ## 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-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-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/value-classes-and-structs-c-cx.md b/docs/cppcx/value-classes-and-structs-c-cx.md index 4c4cd2cdc8..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) @@ -48,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. @@ -140,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 b3ec2de1dd..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,7 +6,7 @@ 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: 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/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/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/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/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 a4f29be142..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. 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 51653b7cba..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 @@ -26,7 +26,7 @@ To install and use the vcremote remote agent to develop code for iOS, you must f 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. 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 index de5661cf55..4a79c5d200 100644 Binary files a/docs/cross-platform/media/cppmdd-options-ios-new.png and b/docs/cross-platform/media/cppmdd-options-ios-new.png differ 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/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/docfx.json b/docs/docfx.json index 11e30e03f9..389b95cc45 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -38,29 +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.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" }, @@ -99,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", @@ -117,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", - "assembler/**.md": "corob-msft", - "attributes/**.md": "corob-msft", + "index.md": "tylermsft", + "assembler/**.md": "tylermsft", + "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", - "assembler/**.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/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/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 0d805f1c48..51f9e9fe17 100644 --- a/docs/dotnet/for-each-in.md +++ b/docs/dotnet/for-each-in.md @@ -1,17 +1,16 @@ --- title: "for each, in" -description: "C++/CLI for each, in statement description and examples." -ms.date: 04/15/2022 +description: "C++/CLI for each, in, statement descriptions and examples." +ms.date: 06/29/2023 ms.topic: "reference" 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` -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 @@ -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 ``` @@ -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 fcb52b4c31..a47621cd29 100644 --- a/docs/dotnet/functional-stl-clr.md +++ b/docs/dotnet/functional-stl-clr.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: functional (STL/CLR)" title: "functional (STL/CLR)" +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) @@ -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; @@ -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; 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/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-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 0850717e4c..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; 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-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-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/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/queue-stl-clr.md b/docs/dotnet/queue-stl-clr.md index 881b8b1967..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) -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's `Value^`. Similarly, `GContainer` is the same as *`Container`* unless the latter is a ref type, in which case it's `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 @@ -35,10 +34,13 @@ The type of the underlying container. ## Requirements -**Header:** \ +**Header:** `` **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 | @@ -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 @@ -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 one 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 @@ -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 one 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 @@ -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,7 +294,7 @@ int main() } System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -314,23 +320,24 @@ 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 @@ -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 @@ -414,31 +422,32 @@ The member function returns true for an empty controlled sequence. It's equivale ```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 @@ -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 one 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 @@ -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 one 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 @@ -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 @@ -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 @@ -693,22 +706,23 @@ 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 @@ -739,29 +753,30 @@ The member operator copies *`right`* to the object, then returns **`*this`**. Yo ```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 @@ -771,7 +786,7 @@ a b c ## `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 @@ -836,22 +852,23 @@ 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 @@ -910,6 +927,7 @@ uses the existing container *`wrapped`* as the wrapped container. You use it to ```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 @@ -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 @@ -1019,32 +1038,33 @@ The member function returns the length of the controlled sequence. You use it to ```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 @@ -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 @@ -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 @@ -1172,17 +1194,18 @@ The type is a synonym for the template parameter *`Value`*. ```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,7 +1214,7 @@ int main() } System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -1228,28 +1251,29 @@ The operator function returns `!(left == right)`. You use it to test whether *`l ```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 @@ -1299,28 +1323,29 @@ The operator function returns true if, for the lowest position `i` for which `!( ```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 @@ -1370,28 +1395,29 @@ The operator function returns `!(right < left)`. You use it to test whether *`le ```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 @@ -1441,28 +1467,29 @@ The operator function returns true only if the sequences controlled by *`left`* ```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 @@ -1512,28 +1539,29 @@ The operator function returns `right < left`. You use it to test whether *`left` ```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 @@ -1583,28 +1611,29 @@ The operator function returns `!(left < right)`. You use it to test whether *`le ```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/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/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 index f7494a9a27..29a6c931e1 100644 Binary files a/docs/embedded/media/serial-monitor-vscode.png 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 index 568dc18c1d..e247eef5e7 100644 Binary files a/docs/embedded/media/serial-monitor.png and b/docs/embedded/media/serial-monitor.png differ diff --git a/docs/embedded/rtos-view.md b/docs/embedded/rtos-view.md index 3a83a9d766..e5e9b7da9b 100644 --- a/docs/embedded/rtos-view.md +++ b/docs/embedded/rtos-view.md @@ -18,7 +18,7 @@ The RTOS Object View allows users to view various components of an RTOS while de # [Visual Studio Code](#tab/visual-studio-code) -![RTOS View in VSCode](media/rtos-threads-vscode.png) +![RTOS View in VS Code](media/rtos-threads-vscode.png) --- @@ -75,7 +75,7 @@ All features should work by default. ### Zephyr - All thread information is only available if `CONFIG_DEBUG_THREAD_INFO` is enabled. -- Thread stack usage is only availabe if `CONFIG_INIT_STACKS` and `CONFIG_THREAD_STACK_INFO` are 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 index 1ae5288388..6ec62acf7e 100644 --- a/docs/embedded/serial-monitor.md +++ b/docs/embedded/serial-monitor.md @@ -14,19 +14,16 @@ The Serial Monitor allows users to configure, monitor, and communicate with seri # [Visual Studio](#tab/visual-studio) -![Serial Monitor in VS](media/serial-monitor.png) - -# [Visual Studio Code](#tab/visual-studio-code) - -![Serial Monitor in VSCode](media/serial-monitor-vscode.png) - ---- +:::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** button to send the data. +- **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 @@ -35,6 +32,58 @@ The Serial Monitor allows users to configure, monitor, and communicate with seri |--|--|--|--| | **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 | +| **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 | -| **Auto-scroll** | Whether to auto-scroll new content that comes from the connected port | Use the **auto-scroll** 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 index f05018c272..01279ba35c 100644 --- a/docs/embedded/toc.yml +++ b/docs/embedded/toc.yml @@ -1,5 +1,5 @@ items: -- name: Embedded development with Visual Studio and Visual Studio code +- 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 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-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 index aa1bd0032b..ab9dba93d8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2023.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2023.md @@ -12,3 +12,22 @@ helpviewer_keywords: ["C2023"] 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 index d5535e724e..fe0b5e057f 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2024.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2024.md @@ -12,3 +12,22 @@ helpviewer_keywords: ["C2024"] 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-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 index f4e39b6902..cc707acda1 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2049.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2049.md @@ -12,3 +12,21 @@ helpviewer_keywords: ["C2049"] 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-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-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-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-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-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-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 1ce2757fd8..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" +description: "Learn more about: Compiler errors C2001 through C2099" +title: "Compiler errors C2001 through C2099" ms.date: 08/24/2022 -f1_keywords: ["C2000", "C2029"] -helpviewer_keywords: ["C2000", "C2029"] -ms.assetid: d99a19eb-eeeb-4181-9b33-9cbe4459767b +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. @@ -16,20 +15,19 @@ The articles in this section of the documentation explain a subset of the error | 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 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) | reuse of macro formal '*identifier*' | +| [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) | missing '>' | +| [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 | @@ -91,7 +89,7 @@ The articles in this section of the documentation explain a subset of the error | [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*': array 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 | @@ -104,11 +102,11 @@ The articles in this section of the documentation explain a subset of the error | [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 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 | +| [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* | @@ -120,4 +118,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-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 5e14408195..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: 08/17/2022 -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", "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", "C1901", "C1906", "C1907"] -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. @@ -16,8 +15,6 @@ The articles in this section of the documentation explain a subset of the error | Error | Message | |--|--| -| [Fatal error C999](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 C1000](fatal-error-c1000-c1999.md) | UNKNOWN FATAL ERROR
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](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 | @@ -29,7 +26,7 @@ The articles in this section of the documentation explain a subset of the error | [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 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 | @@ -45,6 +42,7 @@ The articles in this section of the documentation explain a subset of the error | [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*' | @@ -104,6 +102,7 @@ The articles in this section of the documentation explain a subset of the error | [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* | @@ -112,12 +111,13 @@ The articles in this section of the documentation explain a subset of the 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 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 | @@ -131,7 +131,7 @@ The articles in this section of the documentation explain a subset of the error | 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) | managed targeted code requires a '`/clr`' option | +| [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 | @@ -155,6 +155,7 @@ The articles in this section of the documentation explain a subset of the error | 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*' | @@ -207,7 +208,6 @@ The articles in this section of the documentation explain a subset of the error | [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 | -| [Fatal error C1999](fatal-error-c1000-c1999.md) | UNKNOWN FATAL 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 diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1000-c1999.md b/docs/error-messages/compiler-errors-1/fatal-error-c1000-c1999.md deleted file mode 100644 index 756c66e60c..0000000000 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1000-c1999.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -description: "Learn more about: Fatal Error C1000, C1999" -title: "Fatal Error C1000, C1999" -ms.date: 08/17/2022 -f1_keywords: ["C1000", "C1999"] -helpviewer_keywords: ["C1000", "C1999"] ---- -# Fatal error C1000, C1999 - -> UNKNOWN FATAL ERROR Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information - -This error sometimes means that you have mixed files from different versions of the compiler, or your compiler installation is corrupted. Use the Visual Studio Installer, the System Settings for **Apps & features**, or the Control panel's **Add or remove programs** to repair or reinstall the product. 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 similarity index 100% rename from docs/error-messages/compiler-errors-1/fatal-error-C1015.md rename to docs/error-messages/compiler-errors-1/fatal-error-c1015.md index e407271389..71edb00f18 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-C1015.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1015.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Fatal Error C1015" title: "Fatal Error C1015" +description: "Learn more about: Fatal Error C1015" ms.date: 08/17/2022 f1_keywords: ["C1015"] helpviewer_keywords: ["C1015"] 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 0161cfa61d..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). -## 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-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-c999.md b/docs/error-messages/compiler-errors-1/fatal-error-c999.md deleted file mode 100644 index da7452aec0..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: 08/17/2022 -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 sometimes means that you have mixed files from different versions of the compiler, or your compiler installation is corrupted. Use the Visual Studio Installer, the System Settings for **Apps & features**, or the Control panel's **Add or remove programs** 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-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-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-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-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-c2956.md b/docs/error-messages/compiler-errors-2/compiler-error-c2956.md index e44cae489f..d5fc918703 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2956.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2956.md @@ -17,7 +17,7 @@ Error C2956 indicates you used a *placement new expression* (a `new` expression 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: +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 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-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-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-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 f2f7e9ae44..f46601d681 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3859.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3859.md @@ -4,12 +4,31 @@ title: "Compiler Error C3859" 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 3675124e82..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,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3861" title: "Compiler Error C3861" +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 @@ -98,7 +97,7 @@ int main() { ### ADL and friend functions -The following sample generates C3767 because the compiler can't 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-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 bd932ee66f..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 @@ -4,7 +4,6 @@ title: "Compiler errors C2800 Through C2899" 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 @@ -76,7 +75,7 @@ The articles in this section of the documentation explain a subset of the error | [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 an argument type, except for '(void)' | +| [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 | @@ -108,7 +107,7 @@ The articles in this section of the documentation explain a subset of the error | 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 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 | 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 57c8482859..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 @@ -2,9 +2,8 @@ description: "Learn more about: Compiler errors C2900 Through C2999" title: "Compiler errors C2900 Through C2999" ms.date: 06/01/2022 -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 +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 @@ -99,10 +98,10 @@ The articles in this section of the documentation explain a subset of the error | 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 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 | '*identifier*': __declspec(code_seg(...)) can only be applied to a class or a function | +| 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 | @@ -115,7 +114,6 @@ The articles in this section of the documentation explain a subset of the error | [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 | ## 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 a4abebdc6d..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 @@ -2,9 +2,8 @@ description: "Learn more about: Compiler errors C3000 Through C3099" title: "Compiler errors C3000 Through C3099" ms.date: 06/01/2022 -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 +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 @@ -64,11 +63,11 @@ The articles in this section of the documentation explain a subset of the error | [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) | Expression following '#pragma omp atomic' has improper form | +| [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 doesn't appear in a data-sharing clause under a default(none) clause | +| [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 | @@ -81,8 +80,8 @@ The articles in this section of the documentation explain a subset of the error | [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 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 | @@ -94,7 +93,7 @@ The articles in this section of the documentation explain a subset of the error | [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 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. | 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 9bec78ffec..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 @@ -2,9 +2,8 @@ description: "Learn more about: Compiler errors C3100 Through C3199" title: "Compiler errors C3100 Through C3199" 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", "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 +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 @@ -82,7 +81,7 @@ The articles in this section of the documentation explain a subset of the error | [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 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*' | 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 e835858c67..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 @@ -4,7 +4,6 @@ title: "Compiler errors C3200 Through C3299" 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 @@ -64,7 +63,7 @@ The articles in this section of the documentation explain a subset of the error | 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 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.) | @@ -77,7 +76,7 @@ The articles in this section of the documentation explain a subset of the error | 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 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 | @@ -102,7 +101,7 @@ The articles in this section of the documentation explain a subset of the error | [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 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 | 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 550a6e1eb6..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" +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 @@ -17,24 +16,24 @@ The articles in this section of the documentation explain a subset of the error | Error | Message | |--|--| | Compiler error C3300 | '*symbol*': improper format for IDL '*value*' | -| Compiler error C3301 | '*coclass*': coclass cannot be a '*symbol*' interface | +| 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 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 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 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 | @@ -55,7 +54,7 @@ The articles in this section of the documentation explain a subset of the error | 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 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 | @@ -66,8 +65,8 @@ The articles in this section of the documentation explain a subset of the error | [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 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*' | @@ -117,6 +116,8 @@ The articles in this section of the documentation explain a subset of the error | [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 [C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md) \ 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 ce25161b6d..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 @@ -3,8 +3,7 @@ description: "Learn more about: Compiler errors C3400 Through C3499" title: "Compiler errors C3400 Through C3499" 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", "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 +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 @@ -44,7 +43,7 @@ The articles in this section of the documentation explain a subset of the error | 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 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* | @@ -93,8 +92,8 @@ The articles in this section of the documentation explain a subset of the error | 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 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 | @@ -104,16 +103,16 @@ The articles in this section of the documentation explain a subset of the error | [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*' 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 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*': 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 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 | 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 414f0b1067..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" +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", "C3635", "C3636", "C3639", "C3643", "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", "C3837", "C3840", "C3841", "C3843", "C3844", "C3845", "C3847", "C3863", "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", "C3999"] -ms.assetid: bd6f23ad-b300-4e07-8e35-9661cab1585f +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)] @@ -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| @@ -263,7 +263,7 @@ 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| @@ -286,7 +286,7 @@ The articles in this section of the documentation explain a subset of the error |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 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 expression of type void in a coroutine with non-void eventual return type| @@ -297,7 +297,7 @@ 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| @@ -342,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| @@ -372,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 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,17 +391,18 @@ The articles in this section of the documentation explain a subset of the error |Compiler error C3875|call of non-static member function missing argument list| | 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 '%1$L' following '%2s' | +| 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|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| @@ -434,12 +435,14 @@ The articles in this section of the documentation explain a subset of the error |[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|'*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_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|'`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.| @@ -452,6 +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|'`#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| @@ -506,9 +512,8 @@ The articles in this section of the documentation explain a subset of the error |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 *message* 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 8ffe57121d..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", "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", "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' | @@ -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/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/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-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-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-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 b47e246b65..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: 02/22/2022 +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 +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). + 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, a virtual destructor, 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-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-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-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-c4789.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4789.md index 279721640b..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" +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 @@ -19,9 +18,7 @@ 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) 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,7 +28,7 @@ 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 ) ``` @@ -41,7 +38,7 @@ The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enabl ## Examples -The following sample generates C4789. +The following sample generates C4789: ```cpp // C4789.cpp @@ -63,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-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 3540ce83ae..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: 08/30/2022 +ms.date: 04/22/2025 f1_keywords: ["C4146"] helpviewer_keywords: ["C4146"] --- @@ -9,21 +9,20 @@ 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. 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: +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. 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-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-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-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-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 45ce7ece2d..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: 11/07/2022 +ms.date: 01/18/2024 helpviewer_keywords: ["warnings, by compiler version", "cl.exe compiler, setting warning options"] --- # Compiler Warnings by compiler version @@ -12,41 +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.1 | 19.31 | -| Visual Studio 2022 version 17.2 | 19.32 | -| Visual Studio 2022 version 17.3 | 19.33 | +| 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. @@ -54,21 +63,111 @@ 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`**. +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 | implicit fall-through occurs here; are you missing a `break` statement? Use `[[fallthrough]]` when a `break` statement is intentionally omitted between cases | +| [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`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.32`**. | Warning | Message | |--|--| @@ -76,7 +175,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## 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`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.31`**. | Warning | Message | |--|--| @@ -87,12 +186,12 @@ These warnings and all warnings in later versions are suppressed by using the co | 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 | '#pragma omp for': '*symbol*' increases while loop condition uses '*comparison*'; non-terminating loop? | -| C5302 | '#pragma omp for': '*symbol*' decreases while loop condition uses '*comparison*'; non-terminating loop? | +|[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 | |--|--| @@ -102,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 | |--|--| @@ -119,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 | |--|--| @@ -139,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 | |--|--| @@ -154,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` | @@ -173,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 | |--|--| @@ -193,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| |-|-| @@ -216,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 | |--|--| @@ -227,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 | |--|--| @@ -236,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` | @@ -251,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 | |--|--| @@ -260,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 | |--|--| @@ -273,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 | |--|--| @@ -283,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 | |--|--| @@ -316,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)` | @@ -330,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 | |--|--| @@ -398,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` | @@ -424,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` | @@ -444,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` | @@ -457,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` | @@ -486,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 | |--|--| @@ -496,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)'.` | @@ -509,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'` | @@ -529,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 | |--|--| @@ -540,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 4961aca1fd..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 bc648f2588..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 a6462b5ffd..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"] -helpviewer_keywords: ["C4609", "C4658", "C4671", "C4676", "C4689", "C4695", "C4696", "C4719", "C4720", "C4721", "C4728", "C4732", "C4751", "C4752", "C4755", "C4757", "C4767"] -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 (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 81a071396a..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: 11/07/2022 -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", "C4983", "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", "C5057", "C5058", "C5059", "C5060", "C5061", "C5062", "C5063", "C5081", "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", "C5241", "C5242", "C5244", "C5245", "C5246", "C5249", "C5250", "C5251", "C5252", "C5253", "C5254", "C5255", "C5256", "C5257", "C5258", "C5259", "C5260", "C5261", "C5262", "C5263", "C5264", "C5300", "C5301", "C5302"] -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", "C4983", "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", "C5057", "C5058", "C5059", "C5060", "C5061", "C5062", "C5063", "C5081", "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", "C5241", "C5242", "C5244", "C5245", "C5246", "C5249", "C5250", "C5251", "C5252", "C5253", "C5254", "C5255", "C5256", "C5257", "C5258", "C5259", "C5260", "C5261", "C5262", "C5263", "C5264", "C5300", "C5301", "C5302"] +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,233 +24,125 @@ 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 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 (level 3) C4983 | '/analyze:sarif:hashname' ignored because the argument to '/analyze:log' is a single file rather than a directory | -| [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](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) 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) 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](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 | *segment-name* changed after including 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 or 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 | 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, error) C5300 | '#pragma omp atomic': left operand of '*operator*' must match left hand side of assignment-expression | -| Compiler warning (level 1) C5301 | '#pragma omp for': '*symbol*' increases while loop condition uses '*comparison*'; non-terminating loop? | -| Compiler warning (level 1) C5302 | '#pragma omp for': '*symbol*' decreases while loop condition uses '*comparison*'; non-terminating loop? | ## See also 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 702386ed15..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 Learn 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 cd4bb45eae..8109e4d313 100644 --- a/docs/error-messages/toc.yml +++ b/docs/error-messages/toc.yml @@ -86,12 +86,8 @@ 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 C1000, C1999 - href: compiler-errors-1/fatal-error-c1000-c1999.md - name: Fatal error C1001 href: compiler-errors-1/fatal-error-c1001.md - name: Fatal error C1002 @@ -892,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 @@ -931,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 @@ -1045,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 @@ -1220,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 @@ -1375,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 @@ -1530,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 @@ -1699,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 @@ -1866,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 @@ -2005,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 @@ -2174,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 @@ -2315,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 @@ -2490,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 @@ -2599,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 @@ -3169,27 +3167,29 @@ items: 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 @@ -3249,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 @@ -3259,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 @@ -3299,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 @@ -3315,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 @@ -3323,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 @@ -3357,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 @@ -3401,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 @@ -3435,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 @@ -3532,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 @@ -3562,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 @@ -3576,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 @@ -3590,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 @@ -3606,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 @@ -3630,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 @@ -3650,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 @@ -3662,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 @@ -3698,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 @@ -3706,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 @@ -3720,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 @@ -3751,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 @@ -3759,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 @@ -3779,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 @@ -3795,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 @@ -3833,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 @@ -3867,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 @@ -3881,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 @@ -3901,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 @@ -3933,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 @@ -4172,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 @@ -4329,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 @@ -4349,8 +4352,15 @@ items: 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 @@ -4361,6 +4371,14 @@ items: 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 @@ -4821,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/linker-tools-error-lnk1104.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1104.md index ee3486278c..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,7 +120,7 @@ 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! 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 b331f41375..a12ad9a170 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2019.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2019.md @@ -16,7 +16,7 @@ This error message is followed by fatal error [LNK1120](../../error-messages/too ## 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*. It'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: @@ -58,7 +58,7 @@ 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 @@ -86,15 +86,15 @@ For example, if you use an AVX2 intrinsic, but don't specify the [`/ARCH:AVX2`]( ### 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 +### 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 may 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). +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/). **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. +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 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 74ff15798f..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,10 +1,9 @@ --- -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 @@ -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 f99364bede..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: 05/17/2022 -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"] +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) @@ -138,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-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/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/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-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/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/index.yml b/docs/get-started/index.yml index 092c41ca07..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++ 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 0658bad4de..5a251dca67 100644 --- a/docs/get-started/tutorial-console-cpp.md +++ b/docs/get-started/tutorial-console-cpp.md @@ -2,7 +2,7 @@ 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" --- @@ -10,34 +10,37 @@ ms.devlang: "cpp" ::: 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 with options such as create a new project, open an existing project, and more.](./media/calc-vs2022-initial-dialog.png) - - Otherwise, on the menubar in Visual Studio, choose **File** > **New** > **Project**. The **Create a new project** window opens. + :::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::: -1. In the list of project templates, choose **Console App**, then choose **Next**. +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**. - ![Screenshot of the Create a new project dialog, with the Console App template selected.](./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**. - ![Screenshot of the Configure your new project dialog, which has fields for the project name, project location, and so on.](./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. @@ -66,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."::: - ![Screenshot of the Visual Studio Output window showing the result of the build.](./media/calc-vs2019-build-your-project.png "Build the project") +1. To run the code, on the menu bar, select **Debug** > **Start without debugging** (Ctrl+F5). -1. To run the code, on the menu bar, choose **Debug**, **Start without debugging**. + :::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!"::: - ![Screenshot of the Visual Studio Debug Console showing the output: "Hello World!"](./media/calc-vs2019-hello-world-console.png "Run the project") + A console window opens and your app runs within it. - 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! + 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 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. @@ -115,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. + +### 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-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::: - ![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") + 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. - 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**. + 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**. - ![Screenshot of the Visual Studio 2019 Solution Explorer window displaying the Calculator Tutorial project.](./media/calc-vs2019-solution-explorer.png "Solution Explorer") + :::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::: - 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. + You can open a file by double-clicking it in the **Solution Explorer** window. Double-click `Calculator.h` to open it. -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: +1. Replace the contents of **`Calculator.h`** with the following code so that the file now looks like this: ```cpp #pragma once @@ -156,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 showing a tool tip dropdown with Create definition of Calculate in Calculator C P P 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`*: - !["Screenshot of a pop-up displaying the definition of Calculate."](./media/calc-vs2019-pop-up-definition.png) + :::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) @@ -196,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. @@ -232,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; @@ -241,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 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 with a red dot to the left of a line of code, representing 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 showing the Breakpoint Settings pop up and the condition y==0 && oper == '/' for 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 Studio showing 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 Visual Studio Locals window showing the values of local variables.](./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 a tooltip displaying the value of the variable oper, which is the character `/`.](./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. - ![Screenshot of the Visual Studio Debug Console showing the result of dividing by zero, which is inf.](./media/calc-vs2019-divide-by-zero-fail.png "The result of divide by zero") + :::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::: - This result happens because division by zero is undefined, so the program doesn't have a numerical answer to the requested operation. + 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: -### To fix the "divide by zero" error + :::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 is because division by zero is undefined, so the program doesn't have a numerical answer for the requested operation. + +### 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**. 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. @@ -333,48 +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. - :::image type="complex" source="./media/calc-vs2019-final-verification.png" alt-text="Screenshot of the Visual Studio Debug Console showing the final result after changes"::: - The console window displays two lines: 10 / 0 Result is: inf, followed by, 10 / 0 Division by 0 exception. + :::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 @@ -384,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**. - - ![Screenshot of the New Project dialog with the Windows Console Application project type selected and the Name text box set to CalculatorTutorial.](./media/calculator-new-project-dialog.png "The New Project dialog") + :::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::: - 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() @@ -432,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. - ![Screenshot of the Visual Studio Output window showing that the build was successful.](./media/calculator-initial-build-output.png "Build the project") + :::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, choose **Debug**, **Start without debugging**. +1. To run the code, on the menu bar, select **Debug**, **Start without debugging** (Ctrl+F5). - ![Screenshot of the Visual Studio Debug Console showing the output: Hello World!.](./media/calculator-hello-world-console.png "Start 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!"::: - 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! + A console window opens and your app runs within it. + + 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 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; @@ -464,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; } @@ -482,40 +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: - :::image type="complex" source="./media/calculator-first-launch.gif" alt-text="Short video of running the calculator app."::: - Short video showing Debug > Start without debugging. A dialog is visible that asks whether to build because the project is out of date. The checkbox for 'Do not show this dialog again' is selected. 'Yes' is selected to build the project, the calculator project builds, and then launches in a Windows console window. + :::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. -### 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**. - ![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") + :::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::: - 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**. + A class is like a blueprint for an object that does something. In this case, we define a calculator and how it should work. - ![Screenshot of the Solution Explorer window displaying the Calculator Tutorial project.](./media/calculator-solution-explorer.png "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. - 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. + 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**. -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: + :::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::: + + 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 @@ -528,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) @@ -565,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" @@ -594,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) @@ -611,89 +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 Studio showing the user setting a breakpoint which creates a red dot to the left of the line of code.](./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. - :::image type="complex" source="./media/calculator-conditional-breakpoint.gif" alt-text="Set a conditional breakpoint"::: - Short video showing a right-click on the breakpoint. The breakpoint is on the line of code that reads result = c dot Calculate ( x, oper, y). 'Conditions...' is selected in the dropdown which opens the breakpoint settings window. In the text box following the Conditional Expression and Is true dropdowns, the user enters y == 0 && oper == '/', and then selects close to set the 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 showing 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**. - ![Screenshot of the Autos window showing the values of c, oper, result, x, and y.](./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 showing the values of the function's local variables.](./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 when you hover over a variable. The tooltip displays the variable's value.](./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. - ![Short video of stepping over lines in the Calculate function until back in main(). Then hovering over the result variable and seeing its value: inf.](./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. - 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: + :::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::: - ![Screenshot of the Visual Studio Debug Console which shows the result of dividing by zero: inf](./media/calculator-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::: + + 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" @@ -712,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; @@ -729,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 Debug Console which shows the final result after changes. 10 / 0 is entered and the program displays: Division by 0 exception.](./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 index e371aa47e9..6f4430b635 100644 --- a/docs/ide/add-interface-definition-library-method-wizard.md +++ b/docs/ide/add-interface-definition-library-method-wizard.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Use a Microsoft Visual Studio wizard to add a method to an interface definition language (IDL) interface in your project" 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"] @@ -20,7 +20,7 @@ This wizard differs from the [**Add method**](adding-a-method-visual-cpp.md) wiz 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. 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. @@ -42,7 +42,7 @@ The following section describes the wizard interface that you'll use to add a me - **Return type** - The data type returned by the method. The standard way to return error codes from methods defined in an interface is with a `HRESULT`. + 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. 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 afc07efc56..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,15 +1,14 @@ --- description: "Learn more about: Add a class from an ActiveX control" title: "Add a class from an ActiveX control" -ms.date: "03/01/2022" +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). > [!NOTE] > You don't need to create your MFC project with Automation enabled to add a class from an ActiveX control. @@ -26,14 +25,10 @@ An ActiveX control is a reusable software component based on the Component Objec 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. 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/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-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/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 142af682bd..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 in the context of some include statements.](../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 @@ -21,7 +21,7 @@ You can switch between a header file and its corresponding source file. Right-cl 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 options that appear when you right-click a code element. Includes Go To Definition, Peek Definition, and Go To Declaration.](../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 @@ -29,7 +29,7 @@ You can navigate to the definition of a code element with a right-click in the e You can open **Go To** with **Ctrl+,**. This action creates a search box over the document you're editing. -![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.](../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: @@ -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 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.](../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 which has options like Go To Line (Ctrl + G), Go to File (Ctrl + 1, Ctrl + F), and more.](../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 the Find dialog. The user has searched `channel`. Yellow highlights in the file show all the places `Channel` is found.](../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 dialog. The Find in Files page is selected. Options are shown for matching case, the whole word, and so on.](../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 Files search result listing files containing text that matches the search string and an excerpt of each match.](../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,7 +90,7 @@ 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 Find all references results which shows the line where the symbol was found, which file and project it is located in, and so on.](../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 can group results by the following categories: @@ -104,7 +104,7 @@ You can 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 filtering options. Includes Confirmed, Disconfirmed, In comment, and unprocessed. Each shows how many results apply to that category.](../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`. @@ -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 Navigation Bar above the editor window. It shows cryptlib > ChannelSwitch > ChannelMessageSeriesEnd().](../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 cdf11a2cd6..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 @@ -97,7 +97,7 @@ Place the cursor on or just after any type, keyword or function and press **F1** 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 a graph of include files. The graph shows that NAMSPACE DLL .CPP includes Namespace DLL .h, which includes V_10 .H, among other 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 diff --git a/docs/ide/refactoring/change-signature.md b/docs/ide/refactoring/change-signature.md index df104d5976..e8b15f9005 100644 --- a/docs/ide/refactoring/change-signature.md +++ b/docs/ide/refactoring/change-signature.md @@ -2,6 +2,7 @@ description: "Learn more about: Change Signature" title: "Change Signature" ms.date: "09/18/2022" +f1_keywords: ["vc.pkg.refactoring.changesignaturedlg"] --- # Change Signature diff --git a/docs/ide/refactoring/extract-function.md b/docs/ide/refactoring/extract-function.md index 634dc9f291..91a9fc7d79 100644 --- a/docs/ide/refactoring/extract-function.md +++ b/docs/ide/refactoring/extract-function.md @@ -2,6 +2,7 @@ description: "Learn more about: Extract Function" title: "Extract Function" ms.date: "09/18/2022" +f1_keywords: ["vc.pkg.refactoring.extractfuncdlg"] --- # Extract Function diff --git a/docs/ide/refactoring/rename.md b/docs/ide/refactoring/rename.md index 512ae624ea..69bf660156 100644 --- a/docs/ide/refactoring/rename.md +++ b/docs/ide/refactoring/rename.md @@ -2,6 +2,7 @@ description: "Learn more about: Rename" title: "Rename" ms.date: "09/19/2022" +f1_keywords: ["vc.pkg.refactoring.renamedlg"] --- # Rename diff --git a/docs/ide/toc.yml b/docs/ide/toc.yml index a149cbb552..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 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-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/index.yml b/docs/index.yml index 217da74e4c..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 @@ -164,7 +164,7 @@ 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 @@ -172,10 +172,12 @@ additionalContent: - 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 @@ -205,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 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/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 d74d4cbf9a..591cbf0797 100644 --- a/docs/intrinsics/interlockedcompareexchange-intrinsic-functions.md +++ b/docs/intrinsics/interlockedcompareexchange-intrinsic-functions.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: _InterlockedCompareExchange intrinsic functions" title: "_InterlockedCompareExchange intrinsic functions" +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 @@ -152,7 +151,7 @@ The return value is the initial value pointed at by the `Destination` pointer. | 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_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 | \ | 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/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/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 0ee0124923..6aa9851d39 100644 --- a/docs/intrinsics/umulh.md +++ b/docs/intrinsics/umulh.md @@ -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/x64-amd64-intrinsics-list.md b/docs/intrinsics/x64-amd64-intrinsics-list.md index 92f7c81f83..967215bfa0 100644 --- a/docs/intrinsics/x64-amd64-intrinsics-list.md +++ b/docs/intrinsics/x64-amd64-intrinsics-list.md @@ -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) @@ -84,6 +84,8 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_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);` | diff --git a/docs/intrinsics/x86-intrinsics-list.md b/docs/intrinsics/x86-intrinsics-list.md index 7dbe84d0b7..502e7552b8 100644 --- a/docs/intrinsics/x86-intrinsics-list.md +++ b/docs/intrinsics/x86-intrinsics-list.md @@ -61,6 +61,8 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_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);` | @@ -1137,7 +1139,7 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_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_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);` | diff --git a/docs/linux/connect-to-your-remote-linux-computer.md b/docs/linux/connect-to-your-remote-linux-computer.md index 48777fb732..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: 03/14/2022 +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. @@ -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 options pane and CrossPlatform > C plus plus > Connection Manager selected. The Add button is highlighted.](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 which has fields for host name, port, user name, authentication type, and password.](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,17 +86,25 @@ 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. + + 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 ` - 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. + > [!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 of the Connect to Remote System window with the host name and port fields outlined in red to indicate that they are incorrect.](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. @@ -102,36 +116,36 @@ If `ssh` isn't already set up and running on your Linux system, follow these ste ## 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-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 @@ -149,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. @@ -157,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` @@ -175,35 +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 of the Remote Logging screen with options to enable logging, log file location, and whether to log to the output window.](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 an error that the SSH channel couldn't be opened, and a path to log file for more details.](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, you'll see an error 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, an error appears in the CMake output window the first time it invokes `rsync`. -![Screenshot of the output window which shows an Rsync Error that the SSH channel couldn't be opened.](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 @@ -231,7 +249,7 @@ sudo apt install g++ gdb make ninja-build rsync zip ### Fix WSL `localhost` connection problems -When connecting to Windows Subsystem for Linux (WSL) on `localhost`, you may 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`: +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 @@ -254,9 +272,9 @@ To configure an MSBuild project for WSL, see [Configure a Linux project](configu ::: 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 3fff906968..14b4e8c152 100644 --- a/docs/linux/connectionmanager-reference.md +++ b/docs/linux/connectionmanager-reference.md @@ -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,7 +29,13 @@ 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.) + + 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. + + 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. + + 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`. - **`clean`** @@ -48,7 +54,7 @@ The functionality of ConnectionManager.exe is also available in Visual Studio. T 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. + If no connection is specified, the user's default remote connection is used. - **`remove`** \[*connection_id* \| *user\@host* \[**`--port`** *port*]] @@ -57,7 +63,7 @@ The functionality of ConnectionManager.exe is also available in Visual Studio. T - **`remove-all`** Removes all stored connections. - + - **`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). @@ -135,7 +141,7 @@ ConnectionManager.exe remove 1975957870 | `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` +| `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/deploy-run-and-debug-your-linux-project.md b/docs/linux/deploy-run-and-debug-your-linux-project.md index 33d57455ee..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,7 +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.date: 12/5/2024 ms.custom: intro-deployment --- # Deploy, run, and debug your Linux MSBuild project @@ -33,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. + When the remote target is available, you see it listed by name or IP address: ![Screenshot showing a Remote target IP address.](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. + + 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: ![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. 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 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 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 @@ -115,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 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/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" @@ -123,13 +118,15 @@ 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) -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**). +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**). -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 properties of the file main.cpp with the property content = False highlighted.](media/linux-deployable-content.png) @@ -138,7 +135,6 @@ The **Content** property specifies whether the file will be deployed to the remo 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 - @@ -156,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_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 62e7cb3d00..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,14 +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" +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 @@ -18,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 @@ -26,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 of the Windows search box which contains the text: `visual studio installer`.](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 highlighting 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 @@ -99,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 @@ -137,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 @@ -147,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/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 5e18ef6e2a..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 @@ -48,7 +48,7 @@ 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 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). @@ -58,35 +58,35 @@ The examples in this article use Ubuntu 18.04 LTS with OpenSSH server version 7. 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 -m PEM + 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: ```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. 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/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/mfc-activex-controls-using-fonts.md b/docs/mfc/mfc-activex-controls-using-fonts.md index d1db67fe5c..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 @@ -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/reference/application-control.md b/docs/mfc/reference/application-control.md index 8c32271d69..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 @@ -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 043ef933eb..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. @@ -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/ccmdtarget-class.md b/docs/mfc/reference/ccmdtarget-class.md index 6d4a3bb06a..6c3bdf1fc0 100644 --- a/docs/mfc/reference/ccmdtarget-class.md +++ b/docs/mfc/reference/ccmdtarget-class.md @@ -1,7 +1,7 @@ --- -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"] --- @@ -299,7 +299,7 @@ HRESULT GetTypeInfoOfGuid( ### Parameters *`lcid`*\ -A locale identifier ( `LCID`). +A locale identifier (`LCID`). *`guid`*\ The [GUID](/windows/win32/api/guiddef/ns-guiddef-guid) of the type description. diff --git a/docs/mfc/reference/ccommandlineinfo-class.md b/docs/mfc/reference/ccommandlineinfo-class.md index 944fb85dd1..0702885e23 100644 --- a/docs/mfc/reference/ccommandlineinfo-class.md +++ b/docs/mfc/reference/ccommandlineinfo-class.md @@ -1,7 +1,7 @@ --- -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"] --- @@ -83,7 +83,7 @@ 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. 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 81d9b3cb0d..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,10 +276,10 @@ 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): @@ -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 b816e163d4..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 @@ -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 a1613f393f..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 @@ -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 2078bc7bb0..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. diff --git a/docs/mfc/reference/cdaotabledefinfo-structure.md b/docs/mfc/reference/cdaotabledefinfo-structure.md index eef34d4ef3..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 ``` @@ -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 0b0f9fb591..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). @@ -763,11 +765,11 @@ The default user name. A user name can be 1 - 20 characters long and include alp ### 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/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/cdialog-class.md b/docs/mfc/reference/cdialog-class.md index 099d0e3718..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 @@ -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/cdockablepane-class.md b/docs/mfc/reference/cdockablepane-class.md index 159c429e7f..7b65d85589 100644 --- a/docs/mfc/reference/cdockablepane-class.md +++ b/docs/mfc/reference/cdockablepane-class.md @@ -1,6 +1,6 @@ --- -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"] @@ -874,7 +874,7 @@ One of the following status values: 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 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). @@ -1201,7 +1201,7 @@ virtual void OnAfterChangeParent(CWnd* pWndOldParent); ### Parameters -[in] *`pWndOldParent`*\ +[in] *`pWndOldParent`* ### Remarks 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/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/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/cexception-class.md b/docs/mfc/reference/cexception-class.md index bd6b64594a..93f52aba8a 100644 --- a/docs/mfc/reference/cexception-class.md +++ b/docs/mfc/reference/cexception-class.md @@ -143,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. diff --git a/docs/mfc/reference/cfile-class.md b/docs/mfc/reference/cfile-class.md index 85224ecfbd..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 diff --git a/docs/mfc/reference/cfindreplacedialog-class.md b/docs/mfc/reference/cfindreplacedialog-class.md index e2354f49f9..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 @@ -142,7 +141,7 @@ 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)]   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/cframewnd-class.md b/docs/mfc/reference/cframewnd-class.md index 969f96a322..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)] diff --git a/docs/mfc/reference/cframewndex-class.md b/docs/mfc/reference/cframewndex-class.md index e54a96c15b..6c54057b89 100644 --- a/docs/mfc/reference/cframewndex-class.md +++ b/docs/mfc/reference/cframewndex-class.md @@ -1,6 +1,6 @@ --- -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"] @@ -107,7 +107,7 @@ class CFrameWndEx : public CFrameWnd |[`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::WinHelp`](#winhelp)|Invokes either the `WinHelp` application or context related help.| ## Example 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/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 1d14762430..bc6087fc38 100644 --- a/docs/mfc/reference/cinternetsession-class.md +++ b/docs/mfc/reference/cinternetsession-class.md @@ -1,6 +1,6 @@ --- -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"] @@ -72,7 +72,7 @@ For more information about basic Internet programming tasks, see the article [In ## Inheritance Hierarchy [`CObject`](../../mfc/reference/cobject-class.md)\ -    `CInternetSession` + `CInternetSession` ## Requirements @@ -540,7 +540,7 @@ A pointer to a string containing the actual string data to associate with the UR ### 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 diff --git a/docs/mfc/reference/clistctrl-class.md b/docs/mfc/reference/clistctrl-class.md index 8ddf377080..a9e92a75d1 100644 --- a/docs/mfc/reference/clistctrl-class.md +++ b/docs/mfc/reference/clistctrl-class.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: CListCtrl Class" title: "CListCtrl Class" +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`*\ diff --git a/docs/mfc/reference/cmapstringtoob-class.md b/docs/mfc/reference/cmapstringtoob-class.md index f48bf10173..7d7404e995 100644 --- a/docs/mfc/reference/cmapstringtoob-class.md +++ b/docs/mfc/reference/cmapstringtoob-class.md @@ -1,7 +1,7 @@ --- -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"] --- @@ -399,7 +399,7 @@ 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`. diff --git a/docs/mfc/reference/cmdichildwndex-class.md b/docs/mfc/reference/cmdichildwndex-class.md index b0b6eed2b5..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 @@ -62,7 +61,7 @@ class CMDIChildWndEx : public CMDIChildWnd |[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.| @@ -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/cmdiframewndex-class.md b/docs/mfc/reference/cmdiframewndex-class.md index cdf8a46ed9..bae8259df3 100644 --- a/docs/mfc/reference/cmdiframewndex-class.md +++ b/docs/mfc/reference/cmdiframewndex-class.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: CMDIFrameWndEx class" title: "CMDIFrameWndEx Class" +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"] @@ -72,9 +72,9 @@ class CMDIFrameWndEx : public CMDIFrameWnd |[`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::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::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.| @@ -1282,7 +1282,7 @@ Override this method if you want to customize image rendering for the menu item ## `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( @@ -1313,7 +1313,7 @@ Override this member function if you want to process the `WM_ERASEBKGND` message ## `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( 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/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/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 319ba89f9d..585e3e775f 100644 --- a/docs/mfc/reference/cmfcpropertygridctrl-class.md +++ b/docs/mfc/reference/cmfcpropertygridctrl-class.md @@ -1,10 +1,9 @@ --- -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 @@ -179,7 +178,7 @@ virtual HRESULT accSelect( ### Parameters [in] *`flagsSelect`*\ -[in] *`varChild`*\ +[in] *`varChild`* ### Return Value @@ -235,7 +234,7 @@ void AlwaysShowUserToolTip(BOOL bShow = TRUE); ### Parameters -[in] *`bShow`*\ +[in] *`bShow`* ### Remarks @@ -524,7 +523,7 @@ virtual HRESULT get_accChildCount(long* pcountChildren); ### Parameters -[in] *`pcountChildren`*\ +[in] *`pcountChildren`* ### Return Value @@ -538,7 +537,7 @@ virtual HRESULT get_accFocus(VARIANT* pvarChild); ### Parameters -[in] *`pvarChild`*\ +[in] *`pvarChild`* ### Return Value @@ -555,7 +554,7 @@ virtual HRESULT get_accHelp( ### Parameters [in] *`varChild`*\ -[in] *`pszHelp`*\ +[in] *`pszHelp`* ### Return Value @@ -574,7 +573,7 @@ virtual HRESULT get_accHelpTopic( [in] *`pszHelpFile`*\ [in] *`varChild`*\ -[in] *`pidTopic`*\ +[in] *`pidTopic`* ### Return Value @@ -591,7 +590,7 @@ virtual HRESULT get_accKeyboardShortcut( ### Parameters [in] *`varChild`*\ -[in] *`pszKeyboardShortcut`*\ +[in] *`pszKeyboardShortcut`* ### Return Value @@ -605,7 +604,7 @@ virtual HRESULT get_accSelection(VARIANT* pvarChildren); ### Parameters -[in] *`pvarChildren`*\ +[in] *`pvarChildren`* ### Return Value diff --git a/docs/mfc/reference/cmfcpropertygridproperty-class.md b/docs/mfc/reference/cmfcpropertygridproperty-class.md index 31a00e36f8..8bf3752df3 100644 --- a/docs/mfc/reference/cmfcpropertygridproperty-class.md +++ b/docs/mfc/reference/cmfcpropertygridproperty-class.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: CMFCPropertyGridProperty class" title: "CMFCPropertyGridProperty class" -ms.date: "10/12/2022" +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"] --- @@ -1169,7 +1169,7 @@ virtual void OnKillSelection(CMFCPropertyGridProperty*); ### Parameters -[in] *`CMFCPropertyGridProperty*`*\ +[in] *`CMFCPropertyGridProperty*`* ### Remarks @@ -1183,7 +1183,7 @@ virtual void OnPosSizeChanged(CRect); ### Parameters -[in] *`CRect`*\ +[in] *`CRect`* ### Remarks @@ -1259,12 +1259,12 @@ This method supports the following variant types: `VT_INT`, `VT_I2`, `VT_I4`, `V ## `CMFCPropertyGridProperty::OnSetSelection` ```cpp -virtual void OnSetSelection CMFCPropertyGridProperty*); +virtual void OnSetSelection(CMFCPropertyGridProperty*); ``` ### Parameters -[in] *`CMFCPropertyGridProperty*`*\ +[in] *`CMFCPropertyGridProperty*`* ### Remarks 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 a0eb85dd1a..b3ec1757ee 100644 --- a/docs/mfc/reference/cmfcribbonbar-class.md +++ b/docs/mfc/reference/cmfcribbonbar-class.md @@ -1,10 +1,9 @@ --- -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 @@ -119,7 +118,7 @@ class CMFCRibbonBar : public CPane |[`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::ToggleMimimizeState`](#togglemimimizestate)|Toggles the ribbon bar between the minimized and maximized states.| |[`CMFCRibbonBar::TranslateChar`](#translatechar)|| ## Remarks @@ -1305,7 +1304,7 @@ virtual void OnEditContextMenu( ### Parameters [in] *`pEdit`*\ -[in] *`point`*\ +[in] *`point`* ### Remarks @@ -1360,7 +1359,7 @@ virtual BOOL OnShowRibbonContextMenu( [in] *`pWnd`*\ [in] *`x`*\ [in] *`y`*\ -[in] *`pHit`*\ +[in] *`pHit`* ### Return Value @@ -1381,7 +1380,7 @@ virtual BOOL OnShowRibbonQATMenu( [in] *`pWnd`*\ [in] *`x`*\ [in] *`y`*\ -[in] *`pHit`*\ +[in] *`pHit`* ### Return Value 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/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/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/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 236254137a..e71eb71307 100644 --- a/docs/mfc/reference/cmfctoolbar-class.md +++ b/docs/mfc/reference/cmfctoolbar-class.md @@ -1,7 +1,7 @@ --- -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"] --- @@ -2303,7 +2303,7 @@ virtual BOOL LoadBitmapEx( ### Parameters [in] *`params`*\ -[in] *`bLocked`*\ +[in] *`bLocked`* ### Return Value @@ -2317,7 +2317,7 @@ static BOOL __stdcall LoadLargeIconsState(LPCTSTR lpszProfileName = NULL); ### Parameters -[in] *`lpszProfileName`*\ +[in] *`lpszProfileName`* ### Return Value @@ -2577,7 +2577,7 @@ virtual BOOL OnSetAccData(long lVal); ### Parameters -[in] *`lVal`*\ +[in] *`lVal`* ### Return Value @@ -2837,7 +2837,7 @@ static BOOL __stdcall SaveParameters(LPCTSTR lpszProfileName = NULL); ### Parameters -[in] *`lpszProfileName`*\ +[in] *`lpszProfileName`* ### Return Value @@ -3099,7 +3099,7 @@ static void __stdcall SetHelpMode(BOOL bOn = TRUE); ### Parameters -[in] *`bOn`*\ +[in] *`bOn`* ### Remarks @@ -3111,7 +3111,7 @@ BOOL SetHot(CMFCToolBarButton* pMenuButton); ### Parameters -[in] *`pMenuButton`*\ +[in] *`pMenuButton`* ### Return Value @@ -3161,7 +3161,7 @@ void SetIgnoreSetText(BOOL bValue); ### Parameters -[in] *`bValue`*\ +[in] *`bValue`* ### Remarks @@ -3222,7 +3222,7 @@ void SetMaskMode(BOOL bMasked); ### Parameters -[in] *`bMasked`*\ +[in] *`bMasked`* ### Remarks @@ -3295,7 +3295,7 @@ void SetOrigButtons(const CObList& lstOrigButtons); ### Parameters -[in] *`lstOrigButtons`*\ +[in] *`lstOrigButtons`* ### Remarks @@ -3472,7 +3472,7 @@ This method generates an assertion failure in Debug builds if the specified `CMF 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` 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/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/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 06932c8dff..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; @@ -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/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/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/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 b24ab2f964..4029567072 100644 --- a/docs/mfc/reference/crecordset-class.md +++ b/docs/mfc/reference/crecordset-class.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: CRecordset Class" title: "CRecordset Class" +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"] @@ -205,7 +205,7 @@ void Cancel(); ### Remarks -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 "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` @@ -728,7 +728,7 @@ The number of records in the recordset; 0 if the recordset contains no records; ### 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 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. +> 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` @@ -1474,7 +1474,7 @@ 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] -> 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`** 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'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. @@ -1624,7 +1624,7 @@ 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` isn't 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). 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 3acdab323f..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 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/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/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/cstdiofile-class.md b/docs/mfc/reference/cstdiofile-class.md index 9c318985f7..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 @@ -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/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/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 dd4e551d00..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. 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 28e7c3215b..42e892ac90 100644 --- a/docs/mfc/reference/cview-class.md +++ b/docs/mfc/reference/cview-class.md @@ -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 db9e83c08f..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 @@ -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 @@ -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 42271b822e..85b0987718 100644 --- a/docs/mfc/reference/cwinappex-class.md +++ b/docs/mfc/reference/cwinappex-class.md @@ -1,11 +1,11 @@ --- -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"] --- -# `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. @@ -13,7 +13,7 @@ For more detail, see the source code located in the `mfc` folder of your Visual ## Syntax -``` +```cpp class CWinAppEx : public CWinApp ``` @@ -402,7 +402,7 @@ A pointer to the global `CMouseManager` object. ### Remarks -If the mouse manager isn't 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` @@ -970,7 +970,7 @@ virtual BOOL OnWorkspaceIdle(CWnd*); ### Parameters -[in] *`CWnd*`*\ +[in] *`CWnd*`* ### Return Value 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/cwnd-class.md b/docs/mfc/reference/cwnd-class.md index 228d66b735..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 @@ -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 diff --git a/docs/mfc/reference/diagnostic-services.md b/docs/mfc/reference/diagnostic-services.md index 7bd4aab539..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" +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,7 +76,7 @@ Suppresses compiler warnings for the use of deprecated MFC functions. ### Syntax -``` +```cpp _AFX_SECURE_NO_WARNINGS ``` @@ -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,7 +555,7 @@ void AFXAPI AfxDumpStack(DWORD dwTarget = AFX_STACK_DUMP_TARGET_DEFAULT); ### Parameters -*dwTarget*
+*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 @@ -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 @@ -903,5 +902,5 @@ Stack, global, or embedded objects are not enumerated. The pointer passed to `Af ## 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 bfaaba81ce..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)] 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/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-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/standard-dialog-data-exchange-routines.md b/docs/mfc/reference/standard-dialog-data-exchange-routines.md index fd89641996..0af24a8c46 100644 --- a/docs/mfc/reference/standard-dialog-data-exchange-routines.md +++ b/docs/mfc/reference/standard-dialog-data-exchange-routines.md @@ -34,7 +34,7 @@ This topic lists the standard dialog data exchange (DDX) routines used for commo ## `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. +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( 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/setting-the-dialog-boxs-background-color.md b/docs/mfc/setting-the-dialog-boxs-background-color.md index 4d398c8164..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" +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 -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/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/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/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 663bf576e8..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 diff --git a/docs/overview/cpp-conformance-improvements-2019.md b/docs/overview/cpp-conformance-improvements-2019.md index 2285789044..e3b390b72f 100644 --- a/docs/overview/cpp-conformance-improvements-2019.md +++ b/docs/overview/cpp-conformance-improvements-2019.md @@ -2,7 +2,8 @@ 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: 06/29/2022 -ms.technology: "cpp-language" +ms.service: "visual-cpp" +ms.subservice: "cpp-lang" --- # C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2019 @@ -444,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. @@ -464,7 +465,7 @@ We fixed a minor type traits bug, where `add_const_t` and related functions are ### 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 @@ -1248,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 @@ -1933,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` @@ -2078,7 +2079,7 @@ With this change, a destructor is also potentially throwing if it has a virtual 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 throught 16.8 may now bind directly when the types involved differ only by cv-qualifiers. +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. diff --git a/docs/overview/cpp-conformance-improvements.md b/docs/overview/cpp-conformance-improvements.md index 021185d385..2249e10efa 100644 --- a/docs/overview/cpp-conformance-improvements.md +++ b/docs/overview/cpp-conformance-improvements.md @@ -1,14 +1,620 @@ --- title: "C++ conformance improvements in Visual Studio 2022" description: "Microsoft C++ in Visual Studio is improving standards conformance and fixing bugs regularly." -ms.date: 08/08/2022 -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. + +For changes in earlier versions of Visual Studio: + +| 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 @@ -20,7 +626,7 @@ In versions of Visual Studio before Visual Studio 2022 version 17.4, the C++ com 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 may affect binary compatibility. Some enumeration types change size when the conformant fix is enabled. Certain Windows SDK headers include such enumeration definitions. +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 @@ -58,9 +664,9 @@ enum Changed 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, 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`**). +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 may affect binary compatibility. Some enumeration types change size when the conformant fix is enabled. Certain Windows SDK headers include such enumeration definitions. +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 @@ -73,7 +679,7 @@ enum Enum { 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. +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 @@ -135,9 +741,9 @@ bidi.cpp(8): warning C5255: unterminated bidirectional character encountered: 'U ### `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). +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. +This change affects runtime behavior in the specified range of cases: #### Example @@ -182,7 +788,7 @@ This rounded DOWN. 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`**, together with **`/Zc:__STDC__`**. +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 @@ -252,9 +858,9 @@ void f() 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 non-local lambda-expressions +### 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 non-local lambda expression. It emits a new level 4 warning, C5253. +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`**. @@ -267,7 +873,7 @@ In Visual Studio 2022 version 17.1 this code now emits an error: auto incr = [=](int value) { return value + 1; }; -// capture_default.cpp(3,14): error C5253: a non-local lambda cannot have a capture default +// capture_default.cpp(3,14): error C5253: a nonlocal lambda cannot have a capture default // auto incr = [=](int value) { return value + 1; }; // ^ ``` @@ -301,11 +907,11 @@ int main(void) // C4113: 'int (__cdecl *)(char *)' differs in parameter lists from 'int (__cdecl *)(int)' ``` -### Error on a non-dependent `static_assert` +### 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 as soon as 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. +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. +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 @@ -375,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 3843a9419e..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. @@ -363,22 +364,25 @@ You have a couple of good ways to get your report to us. You can use Visual Stud ### 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 our [Feedback System blog entry](/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 a151bf22de..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 @@ -58,7 +58,7 @@ For more information about Git integration with repos in Azure, see [Share your ## 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 3bcebfdf66..3cd59d14be 100644 --- a/docs/overview/visual-cpp-help-and-community.md +++ b/docs/overview/visual-cpp-help-and-community.md @@ -2,7 +2,8 @@ title: "Microsoft C/C++ help and community" 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.technology: "cpp-ide" +ms.service: "visual-cpp" +ms.subservice: "ide" --- # Microsoft C/C++ help and community diff --git a/docs/overview/visual-cpp-in-visual-studio.md b/docs/overview/visual-cpp-in-visual-studio.md index 73a4bb9729..30012947ca 100644 --- a/docs/overview/visual-cpp-in-visual-studio.md +++ b/docs/overview/visual-cpp-in-visual-studio.md @@ -2,7 +2,8 @@ title: "C and C++ in Visual Studio" 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.technology: "cpp-ide" +ms.service: "visual-cpp" +ms.subservice: "ide" helpviewer_keywords: ["Visual C++, home page"] --- # C and C++ in Visual Studio @@ -120,7 +121,7 @@ Create unit tests using the Microsoft Unit Testing Framework for C++, Google Tes ## Write C/C++ applications using Visual Studio -[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)\ @@ -200,7 +201,7 @@ Programming for the common language runtime (CLR). ## 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/). ## Visual Studio C++ feedback and community diff --git a/docs/overview/visual-cpp-language-conformance.md b/docs/overview/visual-cpp-language-conformance.md index dc5cb7c8e6..f24433753c 100644 --- a/docs/overview/visual-cpp-language-conformance.md +++ b/docs/overview/visual-cpp-language-conformance.md @@ -1,8 +1,9 @@ --- title: "Microsoft C/C++ language conformance" description: "Microsoft C and C++ conformance updates by Visual Studio version." -ms.date: 11/07/2022 -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 @@ -86,7 +87,7 @@ 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** | @@ -115,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) | @@ -216,7 +217,7 @@ For details on conformance improvements, see [C++ conformance improvements in Vi |  [`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 | -|  [`P2513R3 char8_t Compatibility and Portability Fix`](https://wg21.link/p2513r3) | VS 2022 17.4 [DR](#note_DR) | +|  [`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 | @@ -479,7 +480,8 @@ A more detailed listing of Standard Library features and bug fixes by product ve |  [`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) | -|  [`P2322R6 ranges::fold_left, ranges::fold_right, etc.​`](https://wg21.link/p2322r6) | no | +|  [`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) | @@ -496,7 +498,7 @@ A more detailed listing of Standard Library features and bug fixes by product ve |  [`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) | no | +|  [`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) | @@ -528,8 +530,8 @@ A group of papers listed together indicates a Standard feature along with one or |  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) | @@ -539,6 +541,7 @@ 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 @@ -567,13 +570,14 @@ A group of papers listed together indicates a Standard feature along with one or **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.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, 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 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 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/). diff --git a/docs/overview/visual-cpp-samples.md b/docs/overview/visual-cpp-samples.md index b372401c58..3898b2ae6c 100644 --- a/docs/overview/visual-cpp-samples.md +++ b/docs/overview/visual-cpp-samples.md @@ -1,11 +1,11 @@ --- 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: @@ -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 ae2d65e257..7889048806 100644 --- a/docs/overview/what-s-new-for-cpp-2019.md +++ b/docs/overview/what-s-new-for-cpp-2019.md @@ -2,7 +2,8 @@ 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 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 aa37d18030..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,52 +1,466 @@ --- 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/08/2022 -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. +# What's new for C++ in Visual Studio 2022 -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?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 -For a summary of new features and bug fixes in Visual Studio in version 17.34, see [Visual Studio 2022 version 17.3 Release Notes](/visualstudio/releases/2022/release-notes-v17.4). +*Released Nov 2022* -- Improved compiler error messages to provide more correct and useful information, especially for concepts. +| 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) | -- Added experimental MSVC flag **`/experimental:log`** to output SARIF build logs to the specified directory. +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`** flag, or **`/std:c++20`** or later, or **`/permissive-`**. - - You can now disable NRVO with the **`/Zc:nrvo-`** flag. - + - 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 pre-included headers when one 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. - +- 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 have been removed, so users will 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) + - 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` @@ -60,91 +474,98 @@ For a summary of new features and bug fixes in Visual Studio in version 17.34, s - [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 -For a summary of new features and bug fixes in Visual Studio in version 17.3, see [Visual Studio 2022 version 17.3 Release Notes](/visualstudio/releases/2022/release-notes-v17.3). +*Released Aug 2022* -- The Arm64EC toolchain is no longer marked as experimental and is ready for production use. +| 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) | -- 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. +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). -We've improved responsiveness of **Go To All**. Previously, results appeared after you stopped typing. In the new experience, results show as you type. - +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, which will work for non-MSBuild scenarios and add greater functionality. - +- 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). - -- We have 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). +- 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 -For a summary of new features and bug fixes in Visual Studio in version 17.2, see [Visual Studio 2022 version 17.1 Release Notes](/visualstudio/releases/2022/release-notes-v17.2). +*Released May 2022* -- Added compiler support for C++23 feature [deducing `this`](https://wg21.link/p0847), available under the **`/std:c++latest`** option. +| 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) | -- Added IntelliSense support for C++23 features [deducing `this`](https://wg21.link/p0847) and [`if consteval`](http://wg21.link/p1938). +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 choose (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's opened in the memory window. - - We've added thread awareness for device targets to the call stack window. + - 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. - -- We've 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 [C++20 Defect Reports project](https://github.com/microsoft/STL/projects/9) 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. - +- 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 -For a summary of new features and bug fixes in Visual Studio in version 17.1, see [Visual Studio 2022 version 17.1 Release Notes](/visualstudio/releases/2022/release-notes-v17.1). +*Released Feb 2022* -- A new **Configure Preset** template has been 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. +| 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) | -- 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 have been upgraded to v13. +A partial list of new features in 17.1: -- 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'll be prompted to activate Visual Studio's CMake integration with a notification. +- 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/). -- Added a new register visualization window for embedded targets, available through **Debug** > **Windows** > **Embedded Registers**. +## What's new for C++ in Visual Studio version 17.0 -- Added a new thread view for RTOS projects, available through **Debug** > **Windows** > **RTOS Objects**. +*Released Nov 2021* -## What's new for C++ in Visual Studio version 17.0 +| 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) | -For a summary of new features and bug fixes in Visual Studio, see [Visual Studio 2022 version 17.0 Release Notes](/visualstudio/releases/2022/release-notes-v17.0). +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++ @@ -161,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". - +- 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** @@ -189,7 +606,7 @@ 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 change is a source-breaking change. Code that previously had undefined behavior at runtime is now rejected with compiler errors. +- [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** @@ -201,10 +618,9 @@ Select Standard Library (STL) improvements are highlighted here. For a comprehen ### 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 @@ -214,32 +630,29 @@ Select Standard Library (STL) improvements are highlighted here. For a comprehen ### 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**. - - 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 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 @@ -255,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. +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 7646a0e689..0000000000 --- a/docs/overview/whats-new-cpp-docs.md +++ /dev/null @@ -1,581 +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 -monikerRange: '>=msvc-160' ---- - -# 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 our [contributor guide overview](/contribute/) if you'd like to learn how to contribute. -s -- [mohammad-ghasemi-dev](https://github.com/mohammad-ghasemi-dev) (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 our [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) 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 d075cb315a..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 diff --git a/docs/parallel/amp/graphics-cpp-amp.md b/docs/parallel/amp/graphics-cpp-amp.md index 1361e75463..2de8ab623c 100644 --- a/docs/parallel/amp/graphics-cpp-amp.md +++ b/docs/parallel/amp/graphics-cpp-amp.md @@ -1,19 +1,22 @@ --- -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. @@ -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/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 ecdee34132..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. 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/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/using-accelerator-and-accelerator-view-objects.md b/docs/parallel/amp/using-accelerator-and-accelerator-view-objects.md index ca58df0c8b..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. @@ -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() @@ -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 3810657905..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,12 +2,15 @@ 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 Runtime containers because no marshaling has to occur. 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/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/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/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/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/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/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/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 22af119951..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: 11/07/2022 +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,7 +97,7 @@ 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 | @@ -111,7 +112,7 @@ 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* | @@ -136,17 +137,25 @@ The following warnings are turned off by default in Visual Studio 2015 and later | 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 | +### 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 | @@ -165,6 +174,10 @@ The following warnings are turned off by default in Visual Studio 2015 and later | [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 | @@ -174,9 +187,11 @@ The following warnings are turned off by default in Visual Studio 2015 and later | 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 (level 1) | implicit fall-through occurs here; are you missing a `break` statement? Use `[[fallthrough]]` when a `break` statement is intentionally omitted between cases 17.4 | +| [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.\ @@ -195,6 +210,9 @@ The following warnings are turned off by default in Visual Studio 2015 and later 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/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-using-directive-cpp.md b/docs/preprocessor/hash-using-directive-cpp.md index 170e412c40..a417e3cdc8 100644 --- a/docs/preprocessor/hash-using-directive-cpp.md +++ b/docs/preprocessor/hash-using-directive-cpp.md @@ -84,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/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/predefined-macros.md b/docs/preprocessor/predefined-macros.md index cc6d2c4f16..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: 07/07/2022 -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_DEFAULT_NEW_ALIGNMENT__", "__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_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.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_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, 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 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 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 also 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__` 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. @@ -60,23 +63,27 @@ The compiler supports these predefined macros specified by the ISO C99, C11, C17 ## 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. @@ -93,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: @@ -230,7 +237,7 @@ 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). @@ -238,47 +245,17 @@ MSVC supports these additional predefined macros. - `_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 | - | Visual Studio 2022 version 17.1 | 1931 | - | Visual Studio 2022 version 17.2 | 1932 | - - 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 @@ -290,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. @@ -343,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/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 b9cd5d9502..b2f07081df 100644 --- a/docs/safeint/safeint-class.md +++ b/docs/safeint/safeint-class.md @@ -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-known-issues.md b/docs/sanitizers/asan-known-issues.md index da50d277f3..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: 04/15/2022 +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,9 @@ These options and functionality are incompatible with [`/fsanitize=address`](../ ## Standard library support -The MSVC standard library (STL) is partially enlightened to understand the AddressSanitizer and provide additional checks. For more information, see [container-overflow error](./error-container-overflow.md). +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). -When annotations are disabled or in versions without support, AddressSanitizer exceptions raised in STL code do still identify true bugs. However, they aren't as precise as they could be. +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: @@ -54,30 +54,45 @@ int main() { } ``` -## 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 dc4f4cd91a..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. -| 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}`* | +### Previous versions -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. +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. + +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,29 +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: + 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 @@ -173,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 88c26da993..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"] --- @@ -32,23 +32,21 @@ 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 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 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 AddressSanitizer -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: +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: @@ -79,14 +77,17 @@ Microsoft recommends you use AddressSanitizer in these three standard workflows: - [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 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 **`/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. +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. + +> [!NOTE] +> AddressSanitizer doesn't support Profile-guided optimization (PGO). AddressSanitizer shouldn't be used in production. The AddressSanitizer libraries (.lib files) are linked for you automatically. For more information, see [AddressSanitizer language, build, and debugging reference](asan-building.md). @@ -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 @@ -138,34 +141,88 @@ 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."::: ## Use AddressSanitizer from Visual Studio: CMake -To enable 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 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. @@ -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 index 0d8efc036e..b4c1e4c783 100644 --- a/docs/sanitizers/error-container-overflow.md +++ b/docs/sanitizers/error-container-overflow.md @@ -1,7 +1,7 @@ --- title: "Error: container-overflow" -description: "Source examples and live debug screenshots for container overflow errors." -ms.date: 04/15/2022 +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"] --- @@ -10,19 +10,20 @@ helpviewer_keywords: ["container-overflow error", "AddressSanitizer error contai > Address Sanitizer Error: Container overflow -In Visual Studio 2022 version 17.2 and later, the MSVC standard library (STL) is partially enlightened to understand the AddressSanitizer. The following container types have inserted extra annotations to detect memory access issues: +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 | -When a standard type has annotations enabled, to avoid one-definition-rule (ODR) violations, each static library and object used to link the binary must also enable those annotations. Effectively, you must build those static libraries and objects with AddressSanitizer enabled. Mixing code with different annotation settings causes an error: +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 by using **`/fsanitize=address`** and annotations enabled. (Annotations are enabled by default.) +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` @@ -48,7 +49,7 @@ int main() { } ``` -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: +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 @@ -59,6 +60,34 @@ devenv /debugexe example1.exe :::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)\ 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/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 9bd6b4ffcd..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" @@ -57,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 0513578df1..2e049415f2 100644 --- a/docs/standard-library/algorithm-functions.md +++ b/docs/standard-library/algorithm-functions.md @@ -5091,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 }; 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 8fc2d50ed5..b79a77b3b3 100644 --- a/docs/standard-library/algorithms.md +++ b/docs/standard-library/algorithms.md @@ -1,42 +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"] --- # 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/ambiguous-local-time.md b/docs/standard-library/ambiguous-local-time.md index ba8c48c825..72dba2eb71 100644 --- a/docs/standard-library/ambiguous-local-time.md +++ b/docs/standard-library/ambiguous-local-time.md @@ -14,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 @@ -98,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 d3380f16f9..29f281de65 100644 --- a/docs/standard-library/array-class-stl.md +++ b/docs/standard-library/array-class-stl.md @@ -1,6 +1,6 @@ --- description: "Learn more about: array Class (C++ Standard Library)" -title: "array Class (C++ Standard Library)| Microsoft Docs" +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"] 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/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 03e99234bc..9ee633323f 100644 --- a/docs/standard-library/atomic-structure.md +++ b/docs/standard-library/atomic-structure.md @@ -250,7 +250,7 @@ The result of the bitwise "and" (`&`). 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. diff --git a/docs/standard-library/auto-ptr-class.md b/docs/standard-library/auto-ptr-class.md index 31235b6c2d..69bdeb67bf 100644 --- a/docs/standard-library/auto-ptr-class.md +++ b/docs/standard-library/auto-ptr-class.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: auto_ptr Class" title: "auto_ptr Class" -ms.date: 06/07/2022 +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). @@ -41,10 +40,10 @@ 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 @@ -59,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 @@ -102,15 +101,15 @@ 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`. @@ -135,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; @@ -212,11 +211,11 @@ public: { x = i; cout << "Constructing " << ( void* )this << " Value: " << x << endl; - }; + } ~Int( ) { cout << "Destructing " << ( void* )this << " Value: " << x << endl; - }; + } int x; @@ -242,7 +241,7 @@ pi2 == pi3 Destructing 00311B88 Value: 6 ``` -### operator= +### `operator=` An assignment operator that transfers ownership from one `auto_ptr` object to another. @@ -255,7 +254,7 @@ auto_ptr& operator=(auto_ptr_ref right) throw(); #### Parameters -*right*\ +*`right`*\ An object of type `auto_ptr`. #### Return Value @@ -264,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`. @@ -284,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->` @@ -304,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` @@ -321,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 @@ -351,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 @@ -378,7 +377,7 @@ public: int m_i; }; void f(auto_ptr arg) { -}; +} int main() { const auto_ptr ciap(new C(1)); @@ -401,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. @@ -434,10 +433,10 @@ public: { x = i; cout << "Constructing " << (void*)this << " Value: " << x << endl; - }; + } ~Int() { cout << "Destructing " << (void*)this << " Value: " << x << endl; - }; + } int x; @@ -463,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`. @@ -473,7 +472,7 @@ void reset(Type* ptr = 0); #### Parameters -*ptr*\ +*`ptr`*\ The pointer specified to replace the stored pointer `myptr`. #### Example @@ -494,11 +493,11 @@ public: { x = i; cout << "Constructing " << (void*)this << " Value: " << x << endl; - }; + } ~Int() { cout << "Destructing " << (void*)this << " Value: " << x << endl; - }; + } int x; }; @@ -525,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/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-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-istream-class.md b/docs/standard-library/basic-istream-class.md index f67eaa3dbf..a5ebefecce 100644 --- a/docs/standard-library/basic-istream-class.md +++ b/docs/standard-library/basic-istream-class.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: basic_istream Class" title: "basic_istream Class" +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"] @@ -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. @@ -451,7 +451,7 @@ 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(istr)`, and then returns `*this`. For more information, see [`ws`](../standard-library/istream-functions.md#ws). diff --git a/docs/standard-library/basic-istream-view-class.md b/docs/standard-library/basic-istream-view-class.md index 1a0de36918..bac05a4dd9 100644 --- a/docs/standard-library/basic-istream-view-class.md +++ b/docs/standard-library/basic-istream-view-class.md @@ -1,5 +1,5 @@ --- -title: "basic_istream_view class (C++ Standard Library)| Microsoft Docs" +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"] @@ -84,7 +84,7 @@ No member functions are inherited from `view_interface`. ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -117,6 +117,7 @@ The best way to create a `basic_istream_view` is by using the [`views::istream`] ### Example: `basic_istream_view`, `istream_view`, and `wistream_view` ```cpp +// requires /std:c++20, or later #include #include #include @@ -210,4 +211,4 @@ None. ## See also [``](ranges.md)\ -[View classes](view-classes.md) \ No newline at end of file +[View classes](view-classes.md) diff --git a/docs/standard-library/basic-istringstream-class.md b/docs/standard-library/basic-istringstream-class.md index 65784d3592..18872277c2 100644 --- a/docs/standard-library/basic-istringstream-class.md +++ b/docs/standard-library/basic-istringstream-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: basic_istringstream Class" title: "basic_istringstream Class" +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 --- @@ -164,7 +163,7 @@ Returns an object of class [basic_string](../standard-library/basic-string-class ### 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-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 1b79c1a3d2..29ff6874a7 100644 --- a/docs/standard-library/basic-ostringstream-class.md +++ b/docs/standard-library/basic-ostringstream-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: basic_ostringstream Class" title: "basic_ostringstream Class" +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 --- @@ -133,7 +132,7 @@ Returns an object of class [basic_string](../standard-library/basic-string-class ### 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-streambuf-class.md b/docs/standard-library/basic-streambuf-class.md index e672081763..4a543f3fef 100644 --- a/docs/standard-library/basic-streambuf-class.md +++ b/docs/standard-library/basic-streambuf-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: basic_streambuf Class" title: "basic_streambuf Class" +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 --- @@ -550,7 +549,7 @@ The size of the buffer. ### Return Value -Returns [setbuf](#setbuf)( `_Buffer`, `count`). +Returns [setbuf](#setbuf)(`_Buffer`, `count`). ## basic_streambuf::pubsync @@ -750,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 @@ -798,7 +797,7 @@ The number of elements read. For more information, see [streamsize](../standard- ### Remarks -The member function returns [xsgetn](#xsgetn)( `ptr`, `count`). +The member function returns [xsgetn](#xsgetn)(`ptr`, `count`). ### Example @@ -898,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 @@ -946,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 @@ -992,7 +991,7 @@ The number of characters inserted into the stream. ### Remarks -The member function returns [xsputn](#xsputn)( `ptr`, `count`). For more information, 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 @@ -1061,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 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. +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 diff --git a/docs/standard-library/basic-string-class.md b/docs/standard-library/basic-string-class.md index d1bb3eb2df..554d5ba8d8 100644 --- a/docs/standard-library/basic-string-class.md +++ b/docs/standard-library/basic-string-class.md @@ -1,7 +1,7 @@ --- title: "basic_string Class" description: "API reference for the Standard C++ string class, `basic_string`." -ms.date: 06/10/2022 +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 @@ -61,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.| @@ -72,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.| @@ -284,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 @@ -318,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 !!!! @@ -1508,6 +1508,7 @@ The number of characters copied. ### Remarks A null character isn't appended to the end of the copy. +This function is Microsoft specific. ### Example @@ -2958,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, @@ -3351,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; } ``` @@ -3365,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=` @@ -4202,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-stringstream-class.md b/docs/standard-library/basic-stringstream-class.md index 998bc38cb2..6b834225d7 100644 --- a/docs/standard-library/basic-stringstream-class.md +++ b/docs/standard-library/basic-stringstream-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: basic_stringstream Class" title: "basic_stringstream Class" +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 --- @@ -87,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`). @@ -129,7 +128,7 @@ Returns an object of class [basic_string](../standard-library/basic-string-class ### 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 01a33ffdc0..a70a5b0f93 100644 --- a/docs/standard-library/bitset-class.md +++ b/docs/standard-library/bitset-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: bitset Class" title: "bitset Class" +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 @@ -246,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 @@ -1321,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; diff --git a/docs/standard-library/bitset-operators.md b/docs/standard-library/bitset-operators.md index bab7cc6b24..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" 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 dedf8adda9..3a4c9f7b2a 100644 --- a/docs/standard-library/choose-enum.md +++ b/docs/standard-library/choose-enum.md @@ -14,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 1525e6032e..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. @@ -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 5127822f11..82bc6ae824 100644 --- a/docs/standard-library/chrono.md +++ b/docs/standard-library/chrono.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: " title: "" +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"] --- @@ -170,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 4f5ff0e47e..865849283d 100644 --- a/docs/standard-library/clock-time-conversion-struct.md +++ b/docs/standard-library/clock-time-conversion-struct.md @@ -1,6 +1,6 @@ --- -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::chrono::clock_time_conversion"] helpviewer_keywords: ["std::chrono [C++], clock_time_conversion"] @@ -44,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 @@ -101,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-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-view-class.md b/docs/standard-library/common-view-class.md index 68d3377c8c..1480712afd 100644 --- a/docs/standard-library/common-view-class.md +++ b/docs/standard-library/common-view-class.md @@ -1,5 +1,5 @@ --- -title: "common_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -63,7 +63,7 @@ This view is useful for passing a range that has different iterator/sentinel typ ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` 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/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-reference.md b/docs/standard-library/cpp-standard-library-reference.md index acc476cecf..6ae574d37e 100644 --- a/docs/standard-library/cpp-standard-library-reference.md +++ b/docs/standard-library/cpp-standard-library-reference.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: C++ Standard Library Reference (STL)" title: "C++ Standard Library Reference" -ms.date: "3/5/2021" +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"] --- @@ -18,11 +18,11 @@ From a historical perspective, "STL" originally referred to the Standard Templat ## 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/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-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 3a43c74acf..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 @@ -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 @@ -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 b3a963ab30..5501b49af9 100644 --- a/docs/standard-library/day-class.md +++ b/docs/standard-library/day-class.md @@ -1,8 +1,8 @@ --- -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++"] --- @@ -13,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 @@ -270,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/deque-class.md b/docs/standard-library/deque-class.md index 62bee49658..8e82314f40 100644 --- a/docs/standard-library/deque-class.md +++ b/docs/standard-library/deque-class.md @@ -1,6 +1,6 @@ --- -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"] @@ -11,9 +11,9 @@ Arranges elements of a given type in a linear arrangement and, like a vector, en ## Syntax -```unstlib -template > -class deque +```cpp +template > +class deque; ``` ### Parameters @@ -56,8 +56,8 @@ Otherwise, inserting or erasing an element invalidates all iterators and referen |-|-| |[`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_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`.| @@ -720,7 +720,7 @@ None of the constructors perform any interim reallocations. ### Example ```cpp -/ compile with: /EHsc +// compile with: /EHsc #include #include #include @@ -1634,7 +1634,7 @@ int main( ) Provides a pointer to an element in a [`deque`](../standard-library/deque-class.md). -```unstlib +```cpp typedef typename Allocator::pointer pointer; ``` 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-iterator-class.md b/docs/standard-library/directory-iterator-class.md index 20425e83c4..b377693eee 100644 --- a/docs/standard-library/directory-iterator-class.md +++ b/docs/standard-library/directory-iterator-class.md @@ -1,14 +1,14 @@ --- description: "Learn more about: directory_iterator Class" title: "directory_iterator Class" -ms.date: 06/10/2022 -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. @@ -16,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). @@ -32,34 +32,34 @@ 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 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.| +|[`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 default constructor behaves as expected. @@ -74,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. @@ -91,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)`. @@ -101,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. @@ -115,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 aren't 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; @@ -128,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`. @@ -139,7 +139,7 @@ The member operator returns `myentry`. const directory_entry& operator*() const; ``` -## directory_iterator::operator-> +## `directory_iterator::operator->` The member function returns `&**this`. @@ -147,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. @@ -158,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 index 5e66708981..84984d30b4 100644 --- a/docs/standard-library/drop-view-class.md +++ b/docs/standard-library/drop-view-class.md @@ -1,5 +1,5 @@ --- -title: "drop_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -56,7 +56,7 @@ For a description of the following entries, see [View class characteristics](vie ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -204,4 +204,4 @@ The underlying range must satisfy [`sized_range`](range-concepts.md#sized_range) [`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) \ No newline at end of file +[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 index 02f2543e1e..be9e17fff8 100644 --- a/docs/standard-library/drop-while-view-class.md +++ b/docs/standard-library/drop-while-view-class.md @@ -1,5 +1,5 @@ --- -title: "drop_while_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -64,7 +64,7 @@ For a description of the following entries, see [View class characteristics](vie ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -100,7 +100,7 @@ The best way to create a `drop_while_view` is by using the [`views::drop_while`] 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`. -### `drop_while_view` example +### Example: `drop_while_view` ```cpp // requires /std:c++20 or later @@ -228,4 +228,4 @@ false [`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) \ No newline at end of file +[view classes](view-classes.md) diff --git a/docs/standard-library/elements-view-class.md b/docs/standard-library/elements-view-class.md index 01583c627a..4197bcf215 100644 --- a/docs/standard-library/elements-view-class.md +++ b/docs/standard-library/elements-view-class.md @@ -1,5 +1,5 @@ --- -title: "elements_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -58,7 +58,7 @@ For a description of the following entries, see [View class characteristics](vie ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -80,7 +80,7 @@ Construct an instance of a `elements_view`. ### Parameters *`base`*\ -The underlying range. +The underlying range. For information about the template parameter type, see [Template parameters](#template-parameters). @@ -118,7 +118,7 @@ int main() {"C++11", 2011}, {"C++14", 2014}, {"C++17", 2017}, - {"c++20", 2020} + {"C++20", 2020} }; // create an elements_view of all the string elements (<1>) from each tuple @@ -132,7 +132,7 @@ int main() // 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 << name << ' '; // C++03 C++11 C++14 C++17 C++98 C++20 } std::cout << '\n'; @@ -260,4 +260,4 @@ The size of the view is only available if the underlying range is a [`sized_rang [`keys_view`](keys-view-class.md)\ [`values_view`](values-view-class.md)\ [View classes](view-classes.md)\ -[``](ranges.md) \ No newline at end of file +[``](ranges.md) diff --git a/docs/standard-library/empty-view-class.md b/docs/standard-library/empty-view-class.md index 67adb0d220..6d64eedb50 100644 --- a/docs/standard-library/empty-view-class.md +++ b/docs/standard-library/empty-view-class.md @@ -1,5 +1,5 @@ --- -title: "empty_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -64,7 +64,7 @@ Another use for `empty_view` is splitting a [`split_view`](split-view-class.md) ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` 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-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 9a4bb00cef..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 eef418109a..2c642f3180 100644 --- a/docs/standard-library/filesystem-functions.md +++ b/docs/standard-library/filesystem-functions.md @@ -1,6 +1,6 @@ --- -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"] 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"] @@ -129,7 +129,7 @@ The functions all possibly copy the file at *from* to *to* under control of *`op 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`**. diff --git a/docs/standard-library/filter-view-class.md b/docs/standard-library/filter-view-class.md index 23cbc04267..f99b3791bb 100644 --- a/docs/standard-library/filter-view-class.md +++ b/docs/standard-library/filter-view-class.md @@ -1,5 +1,5 @@ --- -title: "filter_view class (C++ Standard Library)| Microsoft Docs" +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"] @@ -58,7 +58,7 @@ For a description of the following entries, see [View class characteristics](vie ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -94,7 +94,7 @@ The best way to create a `filter_view` is by using the [`views::filter`](range-a 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()`. -### `filter_view` example +### Example: `filter_view` ```cpp // requires /std:c++20 or later @@ -216,4 +216,4 @@ int main() [`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) \ No newline at end of file +[view classes](view-classes.md) diff --git a/docs/standard-library/forward-list-class.md b/docs/standard-library/forward-list-class.md index 67b197ffe7..5e8e0a35bd 100644 --- a/docs/standard-library/forward-list-class.md +++ b/docs/standard-library/forward-list-class.md @@ -1,13 +1,13 @@ --- -description: "Learn more about: forward_list Class" title: "forward_list Class" +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`. @@ -21,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` 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 @@ -44,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. @@ -109,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. @@ -129,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. @@ -170,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. @@ -185,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. @@ -199,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. @@ -215,7 +215,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 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(); @@ -224,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. @@ -240,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 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(); @@ -252,7 +252,7 @@ auto i2 = Container.cend(); The value returned by `cend` shouldn't be dereferenced. -## clear +## `clear` Erases all the elements of a forward list. @@ -262,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. @@ -276,7 +276,7 @@ typedef implementation-defined const_iterator; `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. @@ -287,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. @@ -297,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. @@ -309,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. @@ -320,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 @@ -332,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. @@ -345,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. @@ -366,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. @@ -379,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. @@ -390,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). @@ -413,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`. @@ -436,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's `right.get_allocator()`. Otherwise, it's `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)`. @@ -473,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. @@ -486,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. @@ -496,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. @@ -513,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 @@ -537,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. @@ -553,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. @@ -565,7 +565,7 @@ typedef implementation-defined iterator; `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. @@ -579,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. @@ -591,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 @@ -603,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. @@ -619,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. @@ -641,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. @@ -655,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. @@ -666,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. @@ -681,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. @@ -691,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 @@ -700,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. @@ -711,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. @@ -731,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. @@ -749,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. @@ -761,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. @@ -773,7 +773,7 @@ void sort(Predicate pred); ### Parameters -*pred*\ +*`pred`*\ The ordering predicate. ### Remarks @@ -782,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 @@ -813,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. @@ -913,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. @@ -923,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 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. @@ -942,7 +942,7 @@ void unique(BinaryPredicate comp); ### Parameters -*comp*\ +*`comp`*\ The binary predicate used to compare successive elements. ### Remarks @@ -955,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/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 7a26df53f2..3bb0409659 100644 --- a/docs/standard-library/function-class.md +++ b/docs/standard-library/function-class.md @@ -225,7 +225,6 @@ private: int main() { - typedef std::vector< std::function > vf_t; vf_t v; diff --git a/docs/standard-library/functional.md b/docs/standard-library/functional.md index c1ac8dd5bc..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: 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/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/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 adb3a1e83e..61f681bca0 100644 --- a/docs/standard-library/hash-map-class.md +++ b/docs/standard-library/hash-map-class.md @@ -1,7 +1,7 @@ --- -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"] --- @@ -58,7 +58,7 @@ The choice of container type should be based in general on the type of searching 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>`. 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). +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'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. @@ -516,7 +516,7 @@ The data value of the first element in the hash_map is 10. 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 @@ -817,8 +817,8 @@ The [`hash_map::value_type`](#value_type) of an element is a pair, so that the v ```cpp // hash_map_emplace.cpp // compile with: /EHsc -#include -#include +#include +#include #include int main() @@ -878,8 +878,8 @@ Insertion can occur in amortized constant time, instead of logarithmic time, if ```cpp // hash_map_emplace_hint.cpp // compile with: /EHsc -#include -#include +#include +#include #include int main() @@ -1526,7 +1526,7 @@ The position just beyond the last element to be copied from a `hash_map`. 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`. @@ -1545,8 +1545,8 @@ The third member function inserts the sequence of element values into a `hash_ma ```cpp // hash_map_insert.cpp // compile with: /EHsc -#include -#include +#include +#include #include int main() 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/high-resolution-clock-struct.md b/docs/standard-library/high-resolution-clock-struct.md index 2532b4d435..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" +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/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/insert-iterator-class.md b/docs/standard-library/insert-iterator-class.md index 73196c2637..6932e17a30 100644 --- a/docs/standard-library/insert-iterator-class.md +++ b/docs/standard-library/insert-iterator-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: insert_iterator Class" title: "insert_iterator Class" +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 --- @@ -293,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/ios-functions.md b/docs/standard-library/ios-functions.md index 3f8e2af70c..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 diff --git a/docs/standard-library/iota-view-class.md b/docs/standard-library/iota-view-class.md index 250983766e..ecc936307c 100644 --- a/docs/standard-library/iota-view-class.md +++ b/docs/standard-library/iota-view-class.md @@ -1,5 +1,5 @@ --- -title: "iota_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -67,13 +67,13 @@ 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 + std::cout << i << ' '; // 1 2 3 4 5 6 7 8 9 } ``` ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -116,6 +116,7 @@ When you use one of the constructors that value-initializes the bound, the bound ## `iota_view` constructor example ```cpp +// requires /std:c++20, or later #include #include #include diff --git a/docs/standard-library/is-clock-struct.md b/docs/standard-library/is-clock-struct.md index 88dd66a67d..86d02a8daa 100644 --- a/docs/standard-library/is-clock-struct.md +++ b/docs/standard-library/is-clock-struct.md @@ -14,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 @@ -50,14 +50,13 @@ The following code works because `is_clock`, derives from `Cpp17UnaryTypeTrait`, #include #include -using namespace `std::chrono`; +using namespace std::chrono; int main() { is_clock ic; std::cout << std::boolalpha << ic.value << ", " << ic() << ", " << (bool)ic; - return 0; } ``` 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 51710e020e..4961861016 100644 --- a/docs/standard-library/istream-iterator-class.md +++ b/docs/standard-library/istream-iterator-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: istream_iterator Class" title: "istream_iterator Class" +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 --- @@ -15,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, @@ -160,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/iterator-concepts.md b/docs/standard-library/iterator-concepts.md index b26c47b97a..027dd4b630 100644 --- a/docs/standard-library/iterator-concepts.md +++ b/docs/standard-library/iterator-concepts.md @@ -1,6 +1,6 @@ --- -description: "Learn more about iterator concepts." 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"] @@ -70,7 +70,7 @@ In the following table, "Example types" refers to collections/iterators that sat | [`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`.| +| [`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: diff --git a/docs/standard-library/iterator-functions.md b/docs/standard-library/iterator-functions.md index 17de7983ce..99b7df088f 100644 --- a/docs/standard-library/iterator-functions.md +++ b/docs/standard-library/iterator-functions.md @@ -1,6 +1,6 @@ --- -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"] 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++]"] @@ -343,7 +343,7 @@ This iterator returns the elements of the container in reverse order, starting a :::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()."::: -### `crbegin` example +### Example: `crbegin` ```cpp #include @@ -386,7 +386,7 @@ 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 +### `crend` example ```cpp #include @@ -570,7 +570,7 @@ The type of the data in the array. ### Return value -Returns `true` if the container has no elements; otherwise `false.` +Returns `true` if the container has no elements; otherwise `false`. ### Example @@ -1096,7 +1096,7 @@ A reverse iterator to the sentinel at the end of the container. The sentinel fol :::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 +### `rend` example ```cpp #include diff --git a/docs/standard-library/iterator-operators.md b/docs/standard-library/iterator-operators.md index 4175c6c299..27086c18f8 100644 --- a/docs/standard-library/iterator-operators.md +++ b/docs/standard-library/iterator-operators.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: operators" title: " operators" +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=="] helpviewer_keywords: ["std::operator!= (iterator)", "std::operator> (iterator)", "std::operator>= (iterator)", "std::operator< (iterator)", "std::operator<= (iterator), std::operator== (iterator)"] @@ -724,7 +724,7 @@ An iterator. ### Return Value -The difference between two iterators `.` +The difference between two iterators. ### Remarks 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/join-view-class.md b/docs/standard-library/join-view-class.md index e9decfce05..aef74d56cf 100644 --- a/docs/standard-library/join-view-class.md +++ b/docs/standard-library/join-view-class.md @@ -1,5 +1,5 @@ --- -title: "join_view class (C++ Standard Library)| Microsoft Docs" +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"] @@ -60,7 +60,7 @@ This view is useful when you want to combine multiple ranges into a single view. ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -90,6 +90,7 @@ For information about the template parameter type, see [Template parameters](#te ### Example: `join_view` ```cpp +// requires /std:c++20, or later #include #include #include diff --git a/docs/standard-library/keys-view-class.md b/docs/standard-library/keys-view-class.md index d718b4851b..4b9d1e47be 100644 --- a/docs/standard-library/keys-view-class.md +++ b/docs/standard-library/keys-view-class.md @@ -1,5 +1,5 @@ --- -title: "keys_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -59,7 +59,7 @@ The following list of member functions refers to the `keys_view` class. Recall t ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -118,13 +118,13 @@ int main() {"C++11", 2011}, {"C++14", 2014}, {"C++17", 2017}, - {"c++20", 2020} + {"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 << standards << ' '; // C++03 C++11 C++14 C++17 C++98 C++20 } std::cout << '\n'; @@ -244,4 +244,4 @@ The size of the view is only available if the underlying range is a [`sized_rang [`elements_view`](elements-view-class.md)\ [`values_view`](values-view-class.md)\ [``](ranges.md)\ -[View classes](view-classes.md) \ No newline at end of file +[View classes](view-classes.md) diff --git a/docs/standard-library/lazy-split-view-class.md b/docs/standard-library/lazy-split-view-class.md index 4c910228e8..1736de4824 100644 --- a/docs/standard-library/lazy-split-view-class.md +++ b/docs/standard-library/lazy-split-view-class.md @@ -1,5 +1,5 @@ --- -title: "lazy_split_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -71,7 +71,7 @@ For a description of the following entries, see [View class characteristics](vie ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -126,7 +126,7 @@ The best way to create a `lazy_split_view` is by using the [`views::lazy_split`] 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. -### `lazy_split_view` example +### Example: `lazy_split_view` ```cpp // requires /std:c++20 or later @@ -236,6 +236,6 @@ The sentinel that follows the last element in the view: ## See also [``](ranges.md)\ -[`lazy_split` range adaptor](range-adaptors.md#lazy_split) +[`lazy_split` range adaptor](range-adaptors.md#lazy_split)\ [`split_view` class](split-view-class.md)\ -[view classes](view-classes.md) \ No newline at end of file +[view classes](view-classes.md) diff --git a/docs/standard-library/leap-second-info-struct.md b/docs/standard-library/leap-second-info-struct.md index 3f2508e219..fe7095c841 100644 --- a/docs/standard-library/leap-second-info-struct.md +++ b/docs/standard-library/leap-second-info-struct.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: leap_second_info struct" title: "leap_second_info struct" +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"] @@ -20,7 +20,7 @@ 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 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 e856ae1976..b4d78f004b 100644 --- a/docs/standard-library/local_t.md +++ b/docs/standard-library/local_t.md @@ -1,8 +1,8 @@ --- -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", chrono/std::chrono::local_t:local_time", "chrono/std::chrono::local_days", "chrono/std::chrono::local_seconds"] +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++"] --- @@ -34,7 +34,7 @@ As an example of how `local_t` is used, consider the declaration `local_days ld{ |Name|Description| |----------|-----------------| -|`local_days`|A synonym for l`local_time`. 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_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`.| 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/memory-functions.md b/docs/standard-library/memory-functions.md index 7476c9e8b9..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; 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 8930855cff..047db99cf2 100644 --- a/docs/standard-library/month-class.md +++ b/docs/standard-library/month-class.md @@ -13,7 +13,7 @@ Represents a month of a year. For example, July. ## Syntax ```cpp -class month; // C++ 20 +class month; // C++20 ``` ## Remarks diff --git a/docs/standard-library/month-day-class.md b/docs/standard-library/month-day-class.md index 0d1b6cd5a0..a84c17ac08 100644 --- a/docs/standard-library/month-day-class.md +++ b/docs/standard-library/month-day-class.md @@ -65,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 2cf606f60e..7b7780dfbe 100644 --- a/docs/standard-library/month-day-last-class.md +++ b/docs/standard-library/month-day-last-class.md @@ -1,6 +1,6 @@ --- -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"] @@ -14,7 +14,7 @@ dev_langs: ["C++"] ## Syntax ```cpp -class month_day_last; // C++ 20 +class month_day_last; // C++20 ``` ## Members @@ -56,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` @@ -111,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 c7e61138f7..0156b70386 100644 --- a/docs/standard-library/month-weekday-class.md +++ b/docs/standard-library/month-weekday-class.md @@ -14,7 +14,7 @@ Represents the nth weekday of a specific month. ## Syntax ```cpp -class month_weekday; // C++ 20 +class month_weekday; // C++20 ``` ## Remarks @@ -64,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 deb38d3735..34770527f7 100644 --- a/docs/standard-library/month-weekday-last-class.md +++ b/docs/standard-library/month-weekday-last-class.md @@ -1,6 +1,6 @@ --- -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"] @@ -39,7 +39,7 @@ The year is unspecified.\ ## Requirements -**Header:** `` Since C++ 20 +**Header:** `` Since C++20 **Namespace:** `std::chrono` @@ -59,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 935f94c5cb..ca1f45c906 100644 --- a/docs/standard-library/move-iterator-class.md +++ b/docs/standard-library/move-iterator-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: move_iterator Class" title: "move_iterator Class" +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 --- @@ -51,7 +50,7 @@ A `move_iterator` might be capable of operations that aren't defined by the wrap |Operator|Description| |-|-| -|[move_iterator::operator*](#op_star)|Returns `(reference)*base().`| +|[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`.| diff --git a/docs/standard-library/multimap-class.md b/docs/standard-library/multimap-class.md index d0ce3cc3e5..fd24a711eb 100644 --- a/docs/standard-library/multimap-class.md +++ b/docs/standard-library/multimap-class.md @@ -30,7 +30,7 @@ The element data type to be stored in the multimap. *`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`*\ 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 >`. @@ -59,7 +59,7 @@ The `multimap` should be the associative container of choice when the conditions 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 @@ -430,7 +430,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 @@ -1246,7 +1246,6 @@ template void print(const M& m) { int main() { - // insert single values multimap m1; // call insert(const value_type&) version 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/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/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 0df7cbc071..49e1184de8 100644 --- a/docs/standard-library/new-operators.md +++ b/docs/standard-library/new-operators.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: operators and enums" title: " operators and enums" +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 @@ -130,8 +129,8 @@ For information on throwing or non-throwing behavior of `new`, see [The `new` an ```cpp // new_op_new.cpp // compile with: /EHsc -#include -#include +#include +#include using namespace std; diff --git a/docs/standard-library/nonexistent-local-time.md b/docs/standard-library/nonexistent-local-time.md index 1b93e23cef..45529f5820 100644 --- a/docs/standard-library/nonexistent-local-time.md +++ b/docs/standard-library/nonexistent-local-time.md @@ -14,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 @@ -94,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/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-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 f01b65202b..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: @@ -102,7 +102,7 @@ Use these member functions to test for errors while writing to a stream: |[`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: 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/owning-view-class.md b/docs/standard-library/owning-view-class.md index dfcc2c675a..fec32d4b6b 100644 --- a/docs/standard-library/owning-view-class.md +++ b/docs/standard-library/owning-view-class.md @@ -1,5 +1,5 @@ --- -title: "owning_view class (C++ Standard Library)| Microsoft Docs" +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="] @@ -66,7 +66,7 @@ This view is useful when you want a range that doesn't depend on the lifetime of ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` 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/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/range-adaptors.md b/docs/standard-library/range-adaptors.md index 8b7218964a..7fca2c03e4 100644 --- a/docs/standard-library/range-adaptors.md +++ b/docs/standard-library/range-adaptors.md @@ -1,6 +1,6 @@ --- -description: "Learn more about range adaptors, which create views on ranges." 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"] @@ -573,7 +573,7 @@ Create a view that contains the elements of a range that match the specified con ```cpp 1) template - requires requires {filter_view(forward(rg), forward

(predicate));} + requires {filter_view(forward(rg), forward

(predicate));} constexpr ranges::view auto filter(R&& rg, P&& predicate); 2) template @@ -724,7 +724,6 @@ The type of the elements to extract from the stream. 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` @@ -784,7 +783,7 @@ A [`join_view`](join-view-class.md) that contains the elements of all the ranges int main() { // a range of two ranges - std::vector rangeOfRanges[2]{{"C++", "20", "contains:"}, {"ranges", "modules", "concepts & more."}}; + std::vector rangeOfRanges[2]{{"C++20", "contains:"}, {"ranges", "modules", "concepts & more."}}; for (const auto& elem : std::views::join(rangeOfRanges)) { @@ -794,7 +793,7 @@ int main() ``` ```output -C++ 20 contains: ranges modules concepts & more. +C++20 contains: ranges modules concepts & more. ``` ### Remarks @@ -914,7 +913,7 @@ A [`lazy_split_view`](lazy-split-view-class.md) that contains one or more subran 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: +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 | |--|--|--| @@ -1390,7 +1389,7 @@ int main() 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 +template constexpr ranges::view auto values(R&& rg); ``` diff --git a/docs/standard-library/range-concepts.md b/docs/standard-library/range-concepts.md index edb1d88d97..a00aec4ef2 100644 --- a/docs/standard-library/range-concepts.md +++ b/docs/standard-library/range-concepts.md @@ -116,6 +116,14 @@ concept borrowed_range = *`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. @@ -384,7 +392,7 @@ The essential requirement that makes a view composable is that it's cheap to mov - publicly and unambiguously deriving from the empty class `ranges::view_base`, or - specializing `ranges::enable_view` to `true` -Option 1 is generally preferred because `view_interface` also provides default implementation that saves some boilerplate code you have to write. +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. diff --git a/docs/standard-library/range-functions.md b/docs/standard-library/range-functions.md index b242415843..359201dcd0 100644 --- a/docs/standard-library/range-functions.md +++ b/docs/standard-library/range-functions.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: helper functions" 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"] @@ -60,7 +60,7 @@ If `auto(rg.begin())` yields an iterator, returns the equivalent of `auto(rg.beg `ranges::begin()` works on all ranges, whereas `std::begin()` may not. -### `begin` example +### Example: `begin` ```cpp // requires /std:c++20 or later @@ -107,7 +107,7 @@ If `auto(rg.cbegin())` yields an iterator, returns the equivalent of `auto(rg.cb `ranges::cbegin()` works on all ranges, whereas `std::cbegin()` may not. -### `cbegin` example +### Example: `cbegin` ```cpp // requires /std:c++20 or later @@ -145,7 +145,7 @@ A range. 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 *`. -### `cdata` Example +### Example: `cdata` ```cpp #include @@ -193,7 +193,7 @@ The sentinel that follows the last element in the `const`-qualified range: `ranges::cend()` works on all ranges, whereas `std::cend()` may not. -### `cend` example +### Example: `cend` ```cpp // requires /std:c++20 or later @@ -243,7 +243,7 @@ If `auto(rg.crbegin())` yields an iterator, returns the equivalent of `auto(rg.c `ranges::crbegin()` works on all bidirectional ranges, whereas `std::crbegin()` may not. -### `crbegin` example +### Example: `crbegin` ```cpp // requires /std:c++20 or later @@ -289,7 +289,7 @@ The sentinel at the end of what `cbegin()` returns. The sentinel follows the las `ranges::crend()` works on all bidirectional ranges, whereas `std::crend()` may not. -### `crend`example +### `crend` example ```cpp // requires /std:c++20 or later @@ -370,7 +370,7 @@ A range. ### Return value -Returns `true` if the range has no elements; otherwise `false.` +Returns `true` if the range has no elements; otherwise `false`. ### Example 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 ffc526bd0c..68d5e60304 100644 --- a/docs/standard-library/ranges.md +++ b/docs/standard-library/ranges.md @@ -1,7 +1,7 @@ --- title: "" description: "Get an overview of the Standard Template Library (STL) ranges." -ms.date: 12/06/2022 +ms.date: 01/27/2023 f1_keywords: [""] helpviewer_keywords: ["ranges"] --- @@ -80,6 +80,8 @@ int main() } ``` +For more information about views, see [`` view classes](view-classes.md). + ## Range adaptors 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. @@ -98,6 +100,8 @@ The range algorithms are almost identical to the corresponding iterator-pair alg ## `` functions +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. | @@ -114,22 +118,45 @@ The range algorithms are almost identical to the corresponding iterator-pair alg | [`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 concepts +For more information, see [`` functions](range-functions.md). + +## Range concepts 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. 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*. -Some range concepts mirror the hierarchy of iterator categories. The following table lists various range concepts, along with the types of containers that 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::output_range` | Can iterate forward. | -| `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) by 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 diff --git a/docs/standard-library/raw-storage-iterator-class.md b/docs/standard-library/raw-storage-iterator-class.md index 3e8ce70473..0e625fb1ed 100644 --- a/docs/standard-library/raw-storage-iterator-class.md +++ b/docs/standard-library/raw-storage-iterator-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: raw_storage_iterator Class" title: "raw_storage_iterator Class" +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 @@ -114,7 +113,7 @@ public: cout << "Constructing " << i << endl; x = i; bIsConstructed = true; - }; + } Int &operator=(int i) { @@ -123,7 +122,7 @@ public: cout << "Copying " << i << endl; x = i; return *this; - }; + } int x; @@ -190,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; @@ -264,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; } @@ -310,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; }; @@ -335,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/ref-view-class.md b/docs/standard-library/ref-view-class.md index ca064b3500..179d45ce0f 100644 --- a/docs/standard-library/ref-view-class.md +++ b/docs/standard-library/ref-view-class.md @@ -1,5 +1,5 @@ --- -title: "ref_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -57,7 +57,7 @@ For a description of the following entries, see [View class characteristics](vie ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -90,7 +90,7 @@ The best way to create a `ref_view` is by using the [`views::all`](range-adaptor 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. -### `ref_view` example +### Example: `ref_view` ```cpp // requires /std:c++20 or later @@ -213,4 +213,4 @@ The number of elements in the `ref_view`. [``](ranges.md)\ [`all` range adaptor](range-adaptors.md#all)\ -[view classes](view-classes.md) \ No newline at end of file +[view classes](view-classes.md) 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 290bf331a6..afa6499a17 100644 --- a/docs/standard-library/regex.md +++ b/docs/standard-library/regex.md @@ -1,7 +1,7 @@ --- -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"] --- @@ -17,9 +17,9 @@ 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). @@ -81,7 +81,7 @@ To modify the details of the grammar of regular expressions, write a class that |[`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_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.| diff --git a/docs/standard-library/reverse-view-class.md b/docs/standard-library/reverse-view-class.md index 8bff1ad4c0..e344fe82ba 100644 --- a/docs/standard-library/reverse-view-class.md +++ b/docs/standard-library/reverse-view-class.md @@ -1,5 +1,5 @@ --- -title: "reverse_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -57,7 +57,7 @@ For a description of the following entries, see [View class characteristics](vie ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -90,7 +90,7 @@ The best way to create a `reverse_view` is by using the [`views::reverse`](range 1\) The default constructor default-initializes a `reverse_view`.\ 2\) Create a `reverse_view` from the specified view. -### Example: `reverse_view` +### Example: `reverse_view` ```cpp // requires /std:c++20 or later @@ -209,4 +209,4 @@ The size of the view is only available if the underlying range is a [`sized_rang [``](ranges.md)\ [`reverse` range adaptor](range-adaptors.md#reverse)\ -[View classes](view-classes.md) \ No newline at end of file +[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 334806e703..b2b7ae1f19 100644 --- a/docs/standard-library/scoped-allocator-adaptor-class.md +++ b/docs/standard-library/scoped-allocator-adaptor-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: scoped_allocator_adaptor Class" title: "scoped_allocator_adaptor Class" +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 --- @@ -68,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 @@ -240,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 @@ -255,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 @@ -278,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 028b7771bc..76fb181cf4 100644 --- a/docs/standard-library/set-functions.md +++ b/docs/standard-library/set-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: ["set/std::swap (map)", "set/std::swap (multiset)"] -ms.assetid: d1277d14-8502-46c0-b820-bcda820f9406 --- # `` functions @@ -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/single-view-class.md b/docs/standard-library/single-view-class.md index 775d0531a4..7a42d4dfcc 100644 --- a/docs/standard-library/single-view-class.md +++ b/docs/standard-library/single-view-class.md @@ -1,5 +1,5 @@ --- -title: "single_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -62,7 +62,7 @@ The value in the `single_view` can be modified unless the template value is `con ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` diff --git a/docs/standard-library/span-class.md b/docs/standard-library/span-class.md index be60468ddb..010b8fef93 100644 --- a/docs/standard-library/span-class.md +++ b/docs/standard-library/span-class.md @@ -1,5 +1,5 @@ --- -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", @@ -78,7 +78,7 @@ Unlike `array` or `vector`, a `span` doesn't "own" the elements inside it. A `sp ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std` diff --git a/docs/standard-library/span-functions.md b/docs/standard-library/span-functions.md index 456d5c7133..4c92144c44 100644 --- a/docs/standard-library/span-functions.md +++ b/docs/standard-library/span-functions.md @@ -1,6 +1,6 @@ --- -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++]"] @@ -47,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); @@ -87,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); diff --git a/docs/standard-library/split-view-class.md b/docs/standard-library/split-view-class.md index 8e61aa654e..70a26bd73e 100644 --- a/docs/standard-library/split-view-class.md +++ b/docs/standard-library/split-view-class.md @@ -1,5 +1,5 @@ --- -title: "split_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -67,7 +67,7 @@ For a description of the following entries, see [View class characteristics](vie ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -113,7 +113,7 @@ The best way to create a `split_view` is by using the [`views::split`](range-ada 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. -### `split_view` example +### Example `split_view` ```cpp // requires /std:c++20 or later @@ -218,4 +218,4 @@ The sentinel that follows the last element in the view: [``](ranges.md)\ [`split_view` range adaptor](range-adaptors.md#split)\ [`lazy_split_view` class](lazy-split-view-class.md)\ -[view classes](view-classes.md) \ No newline at end of file +[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 fb824672c7..0a392e94bb 100644 --- a/docs/standard-library/sstream-typedefs.md +++ b/docs/standard-library/sstream-typedefs.md @@ -1,19 +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::istringstream", "iosfwd/std::ostringstream", "iosfwd/std::stringbuf", "iosfwd/std::stringstream", "iosfwd/std::wistringstream", "iosfwd/std::wostringstream", "iosfwd/std::wstringbuf", "iosfwd/std::wstringstream"] --- # `` typedefs -[`istringstream`](#istringstream)\ -[`ostringstream`](#ostringstream)\ -[`stringbuf`](#stringbuf)\ -[`stringstream`](#stringstream)\ -[`wistringstream`](#wistringstream)\ -[`wostringstream`](#wostringstream)\ -[`wstringbuf`](#wstringbuf)\ -[`wstringstream`](#wstringstream) +The `` header provides the following typedefs: ## `istringstream` 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 bcb5ea47f5..27c5ae83a4 100644 --- a/docs/standard-library/steady-clock-struct.md +++ b/docs/standard-library/steady-clock-struct.md @@ -1,8 +1,8 @@ --- -description: "Learn more about: steady_clock struct" title: "steady_clock struct" +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"] +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++"] --- @@ -102,4 +102,4 @@ Elapsed nanoseconds: 1007266700 ns [`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-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 48ef23cc2a..7582ab417c 100644 --- a/docs/standard-library/string-view.md +++ b/docs/standard-library/string-view.md @@ -1,7 +1,7 @@ --- title: "" description: "Overview of `basic_string_view`, which refers to a constant contiguous sequence of char-like objects." -ms.date: "9/4/2020" +ms.date: 9/4/2020 helpviewer_keywords: ["string_view header"] --- # `` @@ -37,7 +37,7 @@ The `` operators can compare `string_view` objects to objects of an |[`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_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.| 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/subrange-class.md b/docs/standard-library/subrange-class.md index b0fe6497e7..7f269483d0 100644 --- a/docs/standard-library/subrange-class.md +++ b/docs/standard-library/subrange-class.md @@ -1,5 +1,5 @@ --- -title: "subrange class (C++ Standard Library)| Microsoft Docs" +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"] @@ -49,7 +49,7 @@ For a description of the following entries, see [View class characteristics](vie | **Member functions** | **Description** | |--|--| | [Constructors](#constructors)C++20 | Construct a `subrange`. | -| [`operator PairLike`](#op_pairlike)C++20 | Convert a `subrange`to a pair-like type. | +| [`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. | @@ -70,7 +70,7 @@ A `subrange` is useful when you have a begin and end iterator, but you want to p ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -111,7 +111,7 @@ For information about template parameter types, see [Template parameters](#templ ### Return value -A `subrange`instance. +A `subrange` instance. ### Remarks @@ -123,7 +123,7 @@ A `subrange`instance. The [`counted`](range-adaptors.md#counted) range adaptor can create a `subrange`. That adaptor takes a begin iterator and a count. -### Example: `subrange` +### Example: `counted` ```cpp // requires /std:c++20 or later @@ -192,7 +192,7 @@ std::ranges::subrange std::tuple ``` -### `operator PairLike()` example +### Example: `operator PairLike()` ```cpp // requires /std:c++20 or later @@ -332,7 +332,7 @@ Returns `true` if the `subrange` has no elements. Otherwise, returns `false`. Get the sentinel at the end of the `subrange` ```cpp -[[NODISCARD]] constexpr S end() const; +[[nodiscard]] constexpr S end() const; ``` ### Parameters @@ -467,7 +467,7 @@ return tmp; ```cpp // requires /std:c++20 or later -#include // cout +#include #include #include #include @@ -539,4 +539,4 @@ Changing the position of the `begin` iterator, with `advance`, for example, chan [``](ranges.md)\ [`counted`](range-adaptors.md#counted)\ -[View classes](view-classes.md) \ No newline at end of file +[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 d0e6df8da0..761b5e488a 100644 --- a/docs/standard-library/sys-info-struct.md +++ b/docs/standard-library/sys-info-struct.md @@ -1,6 +1,6 @@ --- -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"] @@ -24,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-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/take-view-class.md b/docs/standard-library/take-view-class.md index 519e895475..a6902be087 100644 --- a/docs/standard-library/take-view-class.md +++ b/docs/standard-library/take-view-class.md @@ -1,5 +1,5 @@ --- -title: "take_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -57,7 +57,7 @@ For a description of the following entries, see [View class characteristics](vie ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -96,7 +96,7 @@ The best way to create a `take_view` is by using the [`views::take`](range-adapt 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. -### `take_view` example +### Example: `take_view` ```cpp // requires /std:c++20 or later @@ -212,6 +212,7 @@ None. 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)`. @@ -219,4 +220,4 @@ If the `take_view` was constructed with an explicit *`count`*: [``](ranges.md)\ [`take` range adaptor](range-adaptors.md#take)\ -[view classes](view-classes.md) \ No newline at end of file +[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 index 0dccbe2589..cfbf93e15b 100644 --- a/docs/standard-library/take-while-view-class.md +++ b/docs/standard-library/take-while-view-class.md @@ -1,5 +1,5 @@ --- -title: "take_while_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -63,7 +63,7 @@ For a description of the following entries, see [View class characteristics](vie ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -102,7 +102,7 @@ The best way to create a `take_while_view` is by using the [`views::take_while`] 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. -### `take_while_view` example +### Example: `take_while_view` ```cpp // requires /std:c++20 or later @@ -239,4 +239,4 @@ int main() [``](ranges.md)\ [`take_view`](take-view-class.md)\ [`take_while` range adaptor](range-adaptors.md#take_while)\ -[view classes](view-classes.md) \ No newline at end of file +[view classes](view-classes.md) diff --git a/docs/standard-library/thread-class.md b/docs/standard-library/thread-class.md index 91c7a8bd6f..e16b853338 100644 --- a/docs/standard-library/thread-class.md +++ b/docs/standard-library/thread-class.md @@ -1,7 +1,7 @@ --- description: "Learn more about: thread Class" title: "thread Class" -ms.date: 06/20/2022 +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 @@ -73,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` @@ -85,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` @@ -97,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 +**Microsoft specific** -`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). +`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. + +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. ## `id` class @@ -125,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(); @@ -143,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`**. @@ -159,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=` @@ -176,7 +178,7 @@ thread& operator=(thread&& Other) noexcept; *`Other`*\ A `thread` object. -### Return Value +### Return value `*this` @@ -214,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`*. @@ -224,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-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-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/toc.yml b/docs/standard-library/toc.yml index 30544a9360..da06070882 100644 --- a/docs/standard-library/toc.yml +++ b/docs/standard-library/toc.yml @@ -797,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 @@ -980,6 +982,8 @@ items: 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: @@ -1445,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 index e80c25dc5b..287645db34 100644 --- a/docs/standard-library/transform-view-class.md +++ b/docs/standard-library/transform-view-class.md @@ -1,5 +1,5 @@ --- -title: "transform_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -61,7 +61,7 @@ For a description of the following entries, see [View class characteristics](vie ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -98,7 +98,7 @@ The best way to create a `transform_view` is by using the [`views::transform`](r 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()`. -### `transform_view` example +### Example: `transform_view` ```cpp // requires /std:c++20 or later @@ -143,7 +143,7 @@ int main() {"Music", Thursday} }; - // lambda to get a reference to the the day of the week for a class + // lambda to get a reference to the day of the week for a class auto getDay = [](classes& c) -> weekday& { return c.startDay; @@ -247,4 +247,4 @@ The number of elements in the view. [``](ranges.md)\ [`filter` range adaptor](range-adaptors.md#filter)\ -[view classes](view-classes.md) \ No newline at end of file +[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 7389b8620f..4dbd2818c3 100644 --- a/docs/standard-library/treat-as-floating-point-structure.md +++ b/docs/standard-library/treat-as-floating-point-structure.md @@ -1,11 +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-size-class-tuple.md b/docs/standard-library/tuple-size-class-tuple.md index e5ed361621..43ca9b50ea 100644 --- a/docs/standard-library/tuple-size-class-tuple.md +++ b/docs/standard-library/tuple-size-class-tuple.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: tuple_size class;" -title: "tuple_size class;" +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 diff --git a/docs/standard-library/type-index-class.md b/docs/standard-library/type-index-class.md index 330d79df38..1d79412bc5 100644 --- a/docs/standard-library/type-index-class.md +++ b/docs/standard-library/type-index-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: type_index Class" title: "type_index Class" +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 --- @@ -29,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`. @@ -37,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 343c082f3d..b43b5a4bae 100644 --- a/docs/standard-library/tzdb-list-class.md +++ b/docs/standard-library/tzdb-list-class.md @@ -13,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 811bbb391d..071c37fda0 100644 --- a/docs/standard-library/tzdb-struct.md +++ b/docs/standard-library/tzdb-struct.md @@ -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/unordered-map-class.md b/docs/standard-library/unordered-map-class.md index 90f5e8ac49..6c477c968a 100644 --- a/docs/standard-library/unordered-map-class.md +++ b/docs/standard-library/unordered-map-class.md @@ -4,7 +4,6 @@ description: "API reference for the C++ Standard Library container class `unorde 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 --- @@ -100,7 +99,7 @@ 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. @@ -2781,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 ab90d089af..1085adc704 100644 --- a/docs/standard-library/unordered-set-class.md +++ b/docs/standard-library/unordered-set-class.md @@ -1,7 +1,7 @@ --- 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"] --- @@ -97,7 +97,7 @@ The allocator class. ## 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. 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 285b3ce509..1521bfbe8e 100644 --- a/docs/standard-library/utc-clock-class.md +++ b/docs/standard-library/utc-clock-class.md @@ -1,6 +1,6 @@ --- -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"] @@ -65,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 diff --git a/docs/standard-library/utility-functions.md b/docs/standard-library/utility-functions.md index fd7da583bf..649d493934 100644 --- a/docs/standard-library/utility-functions.md +++ b/docs/standard-library/utility-functions.md @@ -198,7 +198,6 @@ For the overloads that don't have an `Index` parameter, the element to return is using namespace std; int main() { - typedef pair MyPair; MyPair c0(9, 3.14); 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 afea2e93f1..1cc5c5087a 100644 --- a/docs/standard-library/valarray-class.md +++ b/docs/standard-library/valarray-class.md @@ -1962,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: ( "; @@ -1974,7 +1974,7 @@ 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 ). ``` diff --git a/docs/standard-library/valarray-operators.md b/docs/standard-library/valarray-operators.md index 26fe06609e..47dbac6e27 100644 --- a/docs/standard-library/valarray-operators.md +++ b/docs/standard-library/valarray-operators.md @@ -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,7 +734,7 @@ 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 ). ``` diff --git a/docs/standard-library/values-view-class.md b/docs/standard-library/values-view-class.md index 7c7cd925c4..d069ff09e6 100644 --- a/docs/standard-library/values-view-class.md +++ b/docs/standard-library/values-view-class.md @@ -1,5 +1,5 @@ --- -title: "values_view class (C++ Standard Library)| Microsoft Docs" +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[]"] @@ -57,7 +57,7 @@ For a description of the following entries, see [View class characteristics](vie ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -94,7 +94,7 @@ The best way to create an `values_view` is by using the [`values`](range-adaptor 1) Create an `values_view` from the specified view. 2) The default constructor creates a default-constructed `values_view`. -### Example: `values_view` +### Example: `values_view` ```cpp // requires /std:c++20 or later @@ -102,7 +102,7 @@ The best way to create an `values_view` is by using the [`values`](range-adaptor #include #include #include -#include +#include #include int main() @@ -116,7 +116,7 @@ int main() {"C++11", 2011}, {"C++14", 2014}, {"C++17", 2017}, - {"c++20", 2020} + {"C++20", 2020} }; // Extract all of the values from the map @@ -245,4 +245,4 @@ The size of the view is only available if the underlying range is a [`sized_rang [`elements_view`](elements-view-class.md)\ [`keys_view`](keys-view-class.md)\ [``](ranges.md)\ -[View classes](view-classes.md) \ No newline at end of file +[View classes](view-classes.md) diff --git a/docs/standard-library/vector-bool-class.md b/docs/standard-library/vector-bool-class.md index ddfd8b5a20..8756473a9e 100644 --- a/docs/standard-library/vector-bool-class.md +++ b/docs/standard-library/vector-bool-class.md @@ -1,7 +1,7 @@ --- -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"] --- @@ -350,7 +350,7 @@ The original value of the 3rd element still stored in a bool: false ## `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( 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/view-classes.md b/docs/standard-library/view-classes.md index bf9815b2dd..a7c6a10b81 100644 --- a/docs/standard-library/view-classes.md +++ b/docs/standard-library/view-classes.md @@ -1,6 +1,6 @@ --- -description: "Learn more about the ranges view classes, which allow you to inexpensively transform ranges." 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"] @@ -51,7 +51,7 @@ Using a view after the range that it's based on is modified can lead to undefine 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 +// requires /std:c++20, or later #include #include #include @@ -123,7 +123,7 @@ The following view classes are defined in the `std::ranges` namespace. | [`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. +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 @@ -135,12 +135,12 @@ Each view class topic has a **Characteristics** section after the syntax section * **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. +* **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. - 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." - 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. diff --git a/docs/standard-library/view-interface.md b/docs/standard-library/view-interface.md index c165ead51e..67bf457cb5 100644 --- a/docs/standard-library/view-interface.md +++ b/docs/standard-library/view-interface.md @@ -1,5 +1,5 @@ --- -title: "view_interface class (C++ Standard Library)| Microsoft Docs" +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"] @@ -39,7 +39,7 @@ class view_interface; ## Requirements -**Header:** `` (since C++ 20) +**Header:** `` (since C++20) **Namespace:** `std::ranges` @@ -115,7 +115,7 @@ Returns `true` if the derived view has no elements. Otherwise, returns `false`. ### Remarks -The derived view must satisfy `std::ranges::forward_range`. +The derived view must satisfy `std::ranges::forward_range`. ## `front` @@ -192,7 +192,7 @@ The element at the specified position relative to the beginning iterator. 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`. -### `operator[]` example +### Example: `operator[]` ```cpp // requires /std:c++20 or later @@ -242,7 +242,7 @@ 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`. -### `operator bool` example +### Example: `operator bool` ```cpp // requires /std:c++20 or later 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/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/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 2996d8cccb..88e5800a28 100644 --- a/docs/standard-library/year-month-class.md +++ b/docs/standard-library/year-month-class.md @@ -68,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 f6d55921c4..2427f36c40 100644 --- a/docs/standard-library/year-month-day-last-class.md +++ b/docs/standard-library/year-month-day-last-class.md @@ -70,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 b44e92b1f0..58e7723486 100644 --- a/docs/standard-library/year-month-weekday-class.md +++ b/docs/standard-library/year-month-weekday-class.md @@ -1,6 +1,6 @@ --- -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", "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"] @@ -14,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 @@ -98,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` @@ -325,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 4e58764f6c..8cac30f7d4 100644 --- a/docs/standard-library/year-month-weekday-last-class.md +++ b/docs/standard-library/year-month-weekday-last-class.md @@ -14,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 @@ -74,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 5500c2a5a7..3817f02d55 100644 --- a/docs/standard-library/zoned-time-class.md +++ b/docs/standard-library/zoned-time-class.md @@ -1,8 +1,8 @@ --- -description: "Learn more about: zoned_time class" title: "zoned_time class" +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"] +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++"] --- @@ -131,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 @@ -423,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/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/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/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/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)